<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
           "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<meta name="GENERATOR" content="TtHgold 4.00">
 <style type="text/css"> div.p { margin-top: 7pt;}</style>
 <style type="text/css"><!--
 td div.comp { margin-top: -0.6ex; margin-bottom: -1ex;}
 td div.comb { margin-top: -0.6ex; margin-bottom: -.6ex;}
 td div.hrcomp { line-height: 0.9; margin-top: -0.8ex; margin-bottom: -1ex;}
 td div.norm {line-height:normal;}
 span.roman {font-family: serif; font-style: normal; font-weight: normal;} 
 span.overacc2 {position: relative;  left: .8em; top: -1.2ex;}
 span.overacc1 {position: relative;  left: .6em; top: -1.2ex;} --></style>

<body bgcolor="#FFFFFF">



<title>gSOAP 2.8.22 User Guide</title>
    
<h1 align="center">gSOAP 2.8.22 User Guide </h1>

<h3 align="center">Robert van Engelen <br />GENIVIA INC </h3>

<h3 align="center">Apr 12, 2015
<br />&nbsp; <br /><a href="soapdoc2.pdf"><font color="#FF0000"><b>[This document is also available in PDF format (black and white only)]</b></font></a></h3>
 <br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<h1>Contents </h1><a href="#tth_sEc1"
>1&nbsp; <font color="#0000FF">Introduction</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.1"
>1.1&nbsp; <font color="#0000FF">Getting Started</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.2"
>1.2&nbsp; <font color="#0000FF">Quick Start: Developing a Web Service Client Application</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.3"
>1.3&nbsp; <font color="#0000FF">Quick Start: Developing a Web Service</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.4"
>1.4&nbsp; <font color="#0000FF">Quick Start: XML Data Bindings</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.5"
>1.5&nbsp; <font color="#0000FF">Feature Overview</font></a><br />
<a href="#tth_sEc2"
>2&nbsp; <font color="#0000FF">Notational Conventions</font></a><br />
<a href="#tth_sEc3"
>3&nbsp; <font color="#0000FF">Differences Between gSOAP Versions 2.4 (and Earlier) and 2.5</font></a><br />
<a href="#tth_sEc4"
>4&nbsp; <font color="#0000FF">Differences Between gSOAP Versions 2.1 (and Earlier) and 2.2</font></a><br />
<a href="#tth_sEc5"
>5&nbsp; <font color="#0000FF">Differences Between gSOAP Versions 1.X and 2.X</font></a><br />
<a href="#tth_sEc6"
>6&nbsp; <font color="#0000FF">Interoperability</font></a><br />
<a href="#tth_sEc7"
>7&nbsp; <font color="#0000FF">Quick User Guide</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1"
>7.1&nbsp; <font color="#0000FF">How to Build SOAP/XML Clients</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.1"
>7.1.1&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.2"
>7.1.2&nbsp; <font color="#0000FF">XML Namespace Considerations</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.3"
>7.1.3&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.4"
>7.1.4&nbsp; <font color="#0000FF">How to Generate C++ Client Proxy Classes</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.5"
>7.1.5&nbsp; <font color="#0000FF">XSD Type Encoding Considerations</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.6"
>7.1.6&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.7"
>7.1.7&nbsp; <font color="#0000FF">How to Change the Response Element Name</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.8"
>7.1.8&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.9"
>7.1.9&nbsp; <font color="#0000FF">How to Specify Multiple Output Parameters</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.10"
>7.1.10&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.11"
>7.1.11&nbsp; <font color="#0000FF">How to Specify Output Parameters With struct/class Compound Data Types</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.12"
>7.1.12&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.13"
>7.1.13&nbsp; <font color="#0000FF">How to Specify Anonymous Parameter Names</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.14"
>7.1.14&nbsp; <font color="#0000FF">How to Specify a Method with No Input Parameters</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.1.15"
>7.1.15&nbsp; <font color="#0000FF">How to Specify a Method with No Output Parameters</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2"
>7.2&nbsp; <font color="#0000FF">How to Build SOAP/XML Web Services</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.1"
>7.2.1&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.2"
>7.2.2&nbsp; <font color="#0000FF">MSVC++ Builds</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.3"
>7.2.3&nbsp; <font color="#0000FF">How to Create a Stand-Alone Server</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.4"
>7.2.4&nbsp; <font color="#0000FF">How to Create a Multi-Threaded Stand-Alone Service</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.5"
>7.2.5&nbsp; <font color="#0000FF">How to Pass Application Data to Service Methods</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.6"
>7.2.6&nbsp; <font color="#0000FF">Web Service Implementation Aspects</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.7"
>7.2.7&nbsp; <font color="#0000FF">How to Generate C++ Server Object Classes</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.8"
>7.2.8&nbsp; <font color="#0000FF">How to Chain C++ Server Classes to Accept Messages on the Same Port</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.9"
>7.2.9&nbsp; <font color="#0000FF">How to Generate WSDL Service Descriptions</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.10"
>7.2.10&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.2.11"
>7.2.11&nbsp; <font color="#0000FF">How to Use Client Functionalities Within a Service</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.3"
>7.3&nbsp; <font color="#0000FF">Asynchronous One-Way Message Passing</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.4"
>7.4&nbsp; <font color="#0000FF">Implementing Synchronous One-Way Message Passing over HTTP</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.5"
>7.5&nbsp; <font color="#0000FF">How to Use the SOAP Serializers and Deserializers to Save and Load Application Data using XML Data Bindings</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.5.1"
>7.5.1&nbsp; <font color="#0000FF">Mapping XML Schema to C/C++ with wsdl2h</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.5.2"
>7.5.2&nbsp; <font color="#0000FF">Mapping C/C++ to XML Schema with soapcpp2</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.5.3"
>7.5.3&nbsp; <font color="#0000FF">Serializing C/C++ Data to XML</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.5.4"
>7.5.4&nbsp; <font color="#0000FF">Deserializing C/C++ Data from XML</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.5.5"
>7.5.5&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.5.6"
>7.5.6&nbsp; <font color="#0000FF">Serializing and Deserializing Class Instances to Streams</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc7.5.7"
>7.5.7&nbsp; <font color="#0000FF">How to Specify Default Values for Omitted Data</font></a><br />
<a href="#tth_sEc8"
>8&nbsp; <font color="#0000FF">The wsdl2h WSDL and Schema Importer</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc8.1"
>8.1&nbsp; <font color="#0000FF">wsdl2h Options</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc8.2"
>8.2&nbsp; <font color="#0000FF">Customizing Data Bindings With The typemap.dat File</font></a><br />
<a href="#tth_sEc9"
>9&nbsp; <font color="#0000FF">Using the soapcpp2 Compiler and Code Generator</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.1"
>9.1&nbsp; <font color="#0000FF">soapcpp2 Options</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.2"
>9.2&nbsp; <font color="#0000FF">SOAP 1.1 Versus SOAP 1.2 and Dynamic Switching</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.3"
>9.3&nbsp; <font color="#0000FF">The soapdefs.h Header File</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.4"
>9.4&nbsp; <font color="#0000FF">How to Build Modules and Libraries with the #module Directive</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.5"
>9.5&nbsp; <font color="#0000FF">How to use the #import Directive</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.6"
>9.6&nbsp; <font color="#0000FF">How to Use #include and #define Directives</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.7"
>9.7&nbsp; <font color="#0000FF">Compiling a SOAP/XML Client Application with soapcpp2</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.8"
>9.8&nbsp; <font color="#0000FF">Compiling a SOAP/XML Web Service with soapcpp2</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.9"
>9.9&nbsp; <font color="#0000FF">Compiling Web Services and Clients in ANSI C</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.10"
>9.10&nbsp; <font color="#0000FF">Limitations of gSOAP</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.11"
>9.11&nbsp; <font color="#0000FF">Library Build Flags</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.12"
>9.12&nbsp; <font color="#0000FF">Run Time Flags</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.13"
>9.13&nbsp; <font color="#0000FF">Memory Management</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.13.1"
>9.13.1&nbsp; <font color="#0000FF">Memory Allocation and Management Policies</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.13.2"
>9.13.2&nbsp; <font color="#0000FF">Intra-Class Memory Management</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.14"
>9.14&nbsp; <font color="#0000FF">Debugging</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.15"
>9.15&nbsp; <font color="#0000FF">Generating an Auto Test Server for Client Testing</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc9.16"
>9.16&nbsp; <font color="#0000FF">Required Libraries</font></a><br />
<a href="#tth_sEc10"
>10&nbsp; <font color="#0000FF">The gSOAP Service Operation Specification Format</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc10.1"
>10.1&nbsp; <font color="#0000FF">Service Operation Parameter Passing</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc10.2"
>10.2&nbsp; <font color="#0000FF">Error Codes</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc10.3"
>10.3&nbsp; <font color="#0000FF">C/C++ Identifier Name to XML Tag Name Mapping</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc10.4"
>10.4&nbsp; <font color="#0000FF">Namespace Mapping Table</font></a><br />
<a href="#tth_sEc11"
>11&nbsp; <font color="#0000FF">gSOAP Serialization and Deserialization Rules</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.1"
>11.1&nbsp; <font color="#0000FF">SOAP RPC Encoding Versus Document/Literal and xsi:type Info</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.2"
>11.2&nbsp; <font color="#0000FF">Primitive Type Encoding</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.3"
>11.3&nbsp; <font color="#0000FF">How to Represent Primitive C/C++ Types as XSD Types</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.3.1"
>11.3.1&nbsp; <font color="#0000FF">How to Use Multiple C/C++ Types for a Single Primitive XSD Type</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.3.2"
>11.3.2&nbsp; <font color="#0000FF">How to use C++ Wrapper Classes to Specify Polymorphic Primitive Types</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.3.3"
>11.3.3&nbsp; <font color="#0000FF">XSD Schema Type Decoding Rules</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.3.4"
>11.3.4&nbsp; <font color="#0000FF">Multi-Reference Strings</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.3.5"
>11.3.5&nbsp; <font color="#0000FF">"Smart String" Mixed-Content Decoding</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.3.6"
>11.3.6&nbsp; <font color="#0000FF">C++ Strings</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.3.7"
>11.3.7&nbsp; <font color="#0000FF">Changing the Encoding Precision of <b>float</b>&nbsp;and <b>double</b>&nbsp;Types</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.3.8"
>11.3.8&nbsp; <font color="#0000FF">INF, -INF, and NaN Values of <b>float</b>&nbsp;and <b>double</b>&nbsp;Types</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.4"
>11.4&nbsp; <font color="#0000FF">Enumeration Serialization</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.4.1"
>11.4.1&nbsp; <font color="#0000FF">Serialization of Symbolic Enumeration Constants</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.4.2"
>11.4.2&nbsp; <font color="#0000FF">Encoding of Enumeration Constants</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.4.3"
>11.4.3&nbsp; <font color="#0000FF">Initialized Enumeration Constants</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.4.4"
>11.4.4&nbsp; <font color="#0000FF">How to "Reuse" Symbolic Enumeration Constants</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.4.5"
>11.4.5&nbsp; <font color="#0000FF">Boolean Enumeration Serialization for C</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.4.6"
>11.4.6&nbsp; <font color="#0000FF">Bitmask Enumeration Serialization</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.5"
>11.5&nbsp; <font color="#0000FF">Struct Serialization</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.6"
>11.6&nbsp; <font color="#0000FF">Class Instance Serialization</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.6.1"
>11.6.1&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.6.2"
>11.6.2&nbsp; <font color="#0000FF">Initialized <b>static</b>&nbsp;<b>const</b>&nbsp;Fields</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.6.3"
>11.6.3&nbsp; <font color="#0000FF">Class Methods</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.6.4"
>11.6.4&nbsp; <font color="#0000FF">Getter and Setter Methods</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.6.5"
>11.6.5&nbsp; <font color="#0000FF">Streaming XML with Getter and Setter Methods</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.6.6"
>11.6.6&nbsp; <font color="#0000FF">Polymorphism, Derived Classes, and Dynamic Binding</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.6.7"
>11.6.7&nbsp; <font color="#0000FF">XML Attributes</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.6.8"
>11.6.8&nbsp; <font color="#0000FF">QName Attributes and Elements</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.7"
>11.7&nbsp; <font color="#0000FF">Union Serialization</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.8"
>11.8&nbsp; <font color="#0000FF">Serializing Pointer Types</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.8.1"
>11.8.1&nbsp; <font color="#0000FF">Multi-Referenced Data</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.8.2"
>11.8.2&nbsp; <font color="#0000FF">NULL Pointers and Nil Elements</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.9"
>11.9&nbsp; <font color="#0000FF">Void Pointers</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.10"
>11.10&nbsp; <font color="#0000FF">Fixed-Size Arrays</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11"
>11.11&nbsp; <font color="#0000FF">Dynamic Arrays</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11.1"
>11.11.1&nbsp; <font color="#0000FF">SOAP Array Bounds Limits</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11.2"
>11.11.2&nbsp; <font color="#0000FF">One-Dimensional Dynamic SOAP Arrays</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11.3"
>11.11.3&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11.4"
>11.11.4&nbsp; <font color="#0000FF">One-Dimensional Dynamic SOAP Arrays With Non-Zero Offset</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11.5"
>11.11.5&nbsp; <font color="#0000FF">Nested One-Dimensional Dynamic SOAP Arrays</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11.6"
>11.11.6&nbsp; <font color="#0000FF">Multi-Dimensional Dynamic SOAP Arrays</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11.7"
>11.11.7&nbsp; <font color="#0000FF">Encoding XML Generics Containing Dynamic Arrays</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11.8"
>11.11.8&nbsp; <font color="#0000FF">STL Containers</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11.9"
>11.11.9&nbsp; <font color="#0000FF">Polymorphic Dynamic Arrays and Lists</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.11.10"
>11.11.10&nbsp; <font color="#0000FF">How to Change the Tag Names of the Elements of a SOAP Array or List</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.12"
>11.12&nbsp; <font color="#0000FF">Base64Binary XML Schema Type Encoding</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.13"
>11.13&nbsp; <font color="#0000FF">hexBinary XML Schema Type Encoding</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.14"
>11.14&nbsp; <font color="#0000FF">Literal XML Encoding Style</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc11.14.1"
>11.14.1&nbsp; <font color="#0000FF">Serializing and Deserializing Mixed Content XML With Strings</font></a><br />
<a href="#tth_sEc12"
>12&nbsp; <font color="#0000FF">SOAP Fault Processing</font></a><br />
<a href="#tth_sEc13"
>13&nbsp; <font color="#0000FF">SOAP Header Processing</font></a><br />
<a href="#tth_sEc14"
>14&nbsp; <font color="#0000FF">MIME Attachments</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc14.1"
>14.1&nbsp; <font color="#0000FF">Sending a Collection of MIME Attachments (SwA)</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc14.2"
>14.2&nbsp; <font color="#0000FF">Retrieving a Collection of MIME Attachments (SwA)</font></a><br />
<a href="#tth_sEc15"
>15&nbsp; <font color="#0000FF">DIME Attachments</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc15.1"
>15.1&nbsp; <font color="#0000FF">Sending a Collection of DIME Attachments</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc15.2"
>15.2&nbsp; <font color="#0000FF">Retrieving a Collection of DIME Attachments</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc15.3"
>15.3&nbsp; <font color="#0000FF">Serializing Binary Data in DIME</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc15.4"
>15.4&nbsp; <font color="#0000FF">Streaming DIME</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc15.5"
>15.5&nbsp; <font color="#0000FF">Streaming Chunked DIME</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc15.6"
>15.6&nbsp; <font color="#0000FF">WSDL Bindings for DIME Attachments</font></a><br />
<a href="#tth_sEc16"
>16&nbsp; <font color="#0000FF">MTOM Attachments</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc16.1"
>16.1&nbsp; <font color="#0000FF">Generating MultipartRelated MIME Attachment Bindings in WSDL</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc16.2"
>16.2&nbsp; <font color="#0000FF">Sending and Receiving MTOM Attachments</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc16.3"
>16.3&nbsp; <font color="#0000FF">Streaming MTOM/MIME</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc16.4"
>16.4&nbsp; <font color="#0000FF">Redirecting Inbound MTOM/MIME Streams Based on SOAP Body Content</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc16.5"
>16.5&nbsp; <font color="#0000FF">Streaming Chunked MTOM/MIME</font></a><br />
<a href="#tth_sEc17"
>17&nbsp; <font color="#0000FF">XML Validation</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc17.1"
>17.1&nbsp; <font color="#0000FF">Occurrence Constraints</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc17.1.1"
>17.1.1&nbsp; <font color="#0000FF">Default Values</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc17.1.2"
>17.1.2&nbsp; <font color="#0000FF">Elements with minOccurs and maxOccurs Restrictions</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc17.1.3"
>17.1.3&nbsp; <font color="#0000FF">Required and Prohibited Attributes</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc17.2"
>17.2&nbsp; <font color="#0000FF">Value Constraints</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc17.2.1"
>17.2.1&nbsp; <font color="#0000FF">Data Length Restrictions</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc17.2.2"
>17.2.2&nbsp; <font color="#0000FF">Value Range Restrictions</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc17.2.3"
>17.2.3&nbsp; <font color="#0000FF">Pattern Restrictions</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc17.3"
>17.3&nbsp; <font color="#0000FF">Element and Attribute Qualified/Unqualified Forms</font></a><br />
<a href="#tth_sEc18"
>18&nbsp; <font color="#0000FF">SOAP/XML Over UDP</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc18.1"
>18.1&nbsp; <font color="#0000FF">Using WS-Addressing with SOAP-over-UDP</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc18.2"
>18.2&nbsp; <font color="#0000FF">Client-side One-way Unicast</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc18.3"
>18.3&nbsp; <font color="#0000FF">Client-side One-way Multicast</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc18.4"
>18.4&nbsp; <font color="#0000FF">Client-side Request-Response Unicast</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc18.5"
>18.5&nbsp; <font color="#0000FF">Client-side Request-Response Multicast</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc18.6"
>18.6&nbsp; <font color="#0000FF">SOAP-over-UDP Server</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc18.7"
>18.7&nbsp; <font color="#0000FF">SOAP-over-UDP Multicast Receiving Server</font></a><br />
<a href="#tth_sEc19"
>19&nbsp; <font color="#0000FF">Advanced Features</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.1"
>19.1&nbsp; <font color="#0000FF">Internationalization</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.2"
>19.2&nbsp; <font color="#0000FF">Customizing the WSDL and Namespace Mapping Table File Contents With gSOAP Directives</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.2.1"
>19.2.1&nbsp; <font color="#0000FF">Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.3"
>19.3&nbsp; <font color="#0000FF">Transient Data Types</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.4"
>19.4&nbsp; <font color="#0000FF">Serialization "as is" with Volatile Data Types</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.5"
>19.5&nbsp; <font color="#0000FF">How to Declare User-Defined Serializers and Deserializers</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.6"
>19.6&nbsp; <font color="#0000FF">How to Serialize Data Without Generating XSD Type Attributes</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.7"
>19.7&nbsp; <font color="#0000FF">Function Callbacks for Customized I/O and HTTP Handling</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.8"
>19.8&nbsp; <font color="#0000FF">HTTP 1.0 and 1.1</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.9"
>19.9&nbsp; <font color="#0000FF">HTTP 307 Temporary Redirect Support</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.10"
>19.10&nbsp; <font color="#0000FF">HTTP GET Support</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.11"
>19.11&nbsp; <font color="#0000FF">TCP and HTTP Keep-Alive</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.12"
>19.12&nbsp; <font color="#0000FF">HTTP Chunked Transfer Encoding</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.13"
>19.13&nbsp; <font color="#0000FF">HTTP Buffered Sends</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.14"
>19.14&nbsp; <font color="#0000FF">HTTP Authentication</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.15"
>19.15&nbsp; <font color="#0000FF">HTTP NTLM Authentication</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.16"
>19.16&nbsp; <font color="#0000FF">HTTP Proxy NTLM Authentication</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.17"
>19.17&nbsp; <font color="#0000FF">HTTP Proxy Basic Authentication</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.18"
>19.18&nbsp; <font color="#0000FF">Messaging Speed and Performance Improvement Tips</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.19"
>19.19&nbsp; <font color="#0000FF">Timeout Management for Non-Blocking Operations</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.20"
>19.20&nbsp; <font color="#0000FF">Socket Options and Flags</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.21"
>19.21&nbsp; <font color="#0000FF">Secure Web Services with HTTPS/SSL</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.22"
>19.22&nbsp; <font color="#0000FF">Secure Clients with HTTPS/SSL</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.23"
>19.23&nbsp; <font color="#0000FF">SSL Authentication Callbacks</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.24"
>19.24&nbsp; <font color="#0000FF">SSL Certificates and Key Files</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.25"
>19.25&nbsp; <font color="#0000FF">SSL Hardware Acceleration</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.26"
>19.26&nbsp; <font color="#0000FF">SSL on Windows</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.27"
>19.27&nbsp; <font color="#0000FF">Zlib Compression</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.28"
>19.28&nbsp; <font color="#0000FF">Client-Side Cookie Support</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.29"
>19.29&nbsp; <font color="#0000FF">Server-Side Cookie Support</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.30"
>19.30&nbsp; <font color="#0000FF">Connecting Clients Through Proxy Servers</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.31"
>19.31&nbsp; <font color="#0000FF">FastCGI Support</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.32"
>19.32&nbsp; <font color="#0000FF">How to Create gSOAP Applications With a Small Memory Footprint</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.33"
>19.33&nbsp; <font color="#0000FF">How to Eliminate BSD Socket Library Linkage</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.34"
>19.34&nbsp; <font color="#0000FF">How to Combine Multiple Client and Server Implementations into one Executable</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.35"
>19.35&nbsp; <font color="#0000FF">How to Build a Client or Server in a C++ Code Namespace</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.36"
>19.36&nbsp; <font color="#0000FF">How to Create Client/Server Libraries</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.36.1"
>19.36.1&nbsp; <font color="#0000FF">C++ Clients Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.36.2"
>19.36.2&nbsp; <font color="#0000FF">C Clients Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.36.3"
>19.36.3&nbsp; <font color="#0000FF">C Services Chaining Example</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.37"
>19.37&nbsp; <font color="#0000FF">How to Create DLLs</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.37.1"
>19.37.1&nbsp; <font color="#0000FF">Create the Base stdsoap2.dll</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.37.2"
>19.37.2&nbsp; <font color="#0000FF">Creating Client and Server DLLs</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.38"
>19.38&nbsp; <font color="#0000FF">gSOAP Plug-ins</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.38.1"
>19.38.1&nbsp; <font color="#0000FF">The Message Logging and Statistics Plug-in</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.38.2"
>19.38.2&nbsp; <font color="#0000FF">RESTful Interface: The HTTP GET Plug-in</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.38.3"
>19.38.3&nbsp; <font color="#0000FF">RESTful Interface: The HTTP POST Plug-in</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.38.4"
>19.38.4&nbsp; <font color="#0000FF">The HTTP MD5 Checksum Plug-in</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.38.5"
>19.38.5&nbsp; <font color="#0000FF">The HTTP Digest Authentication Plug-in</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.38.6"
>19.38.6&nbsp; <font color="#0000FF">The WS-Addressing Plug-in</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.38.7"
>19.38.7&nbsp; <font color="#0000FF">The WS-ReliableMessaging Plug-in</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.38.8"
>19.38.8&nbsp; <font color="#0000FF">The WS-Security Plug-in</font></a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc19.38.9"
>19.38.9&nbsp; <font color="#0000FF">WS-Discovery</font></a><br />

</td></tr></table><br></span>
<i>Copyright (C) 2000-2012 Robert A. van Engelen, GENIVIA INC, All Rights Reserved.</i>


<div class="p"><!----></div>
 <h2><a name="tth_sEc1">
1</a>&nbsp;&nbsp;<font color="#0000FF">Introduction</font></h2>

<div class="p"><!----></div>
The gSOAP tools provide an automated SOAP and XML data binding for C and C++
based on compiler technologies.  The tools simplify the development
of SOAP/XML Web services and XML 
application in C and C++ using autocode generation and advanced mapping
methods. Most toolkits for Web services adopt a WSDL/SOAP-centric view and
offer APIs that require the use of class libraries for XML-specific
data structures. This forces a user to adapt the application logic to
these libraries because users have to write code to populate XML and extract
data from XML using a vendor-specific API. This often leads to fragile
solutions with little or no assurances for data consistency, type safety, and
XML validation. By contrast, gSOAP provides a type-safe and transparent
solution through the use of compiler technology that hides irrelevant WSDL-,
SOAP-, REST-, and XML-specific protocol details from the user, while
automatically ensuring XML validity checking, memory management, and type-safe
serialization. The gSOAP tools automatically map native and user-defined C and
C++ data types to semantically equivalent XML data types and vice-versa.  As a
result, full SOAP/REST XML interoperability is achieved with a simple API
relieving the user from the burden of WSDL/SOAP/XML details, thus enabling him
or her to concentrate on the application-essential logic.

<div class="p"><!----></div>
The gSOAP tools support the integration of (legacy) C/C++
codes (and other programming languages when a C interface is available),
embedded systems, and real-time software in SOAP/XML  applications that share
computational resources and information with other SOAP applications, possibly
across different platforms, language environments, and disparate organizations
located behind firewalls.

<div class="p"><!----></div>
The gSOAP tools are also popular to implement XML data binding in C and C++.
This means that application-native data structures can be encoded in XML
automatically, without the need to write conversion code. The tools also
produce XML schemas for the XML data binding, so external applications can
consume the XML data based on the schemas.

<div class="p"><!----></div>
     <h3><a name="tth_sEc1.1">
1.1</a>&nbsp;&nbsp;<font color="#0000FF">Getting Started</font></h3>

<div class="p"><!----></div>
To start building Web services applications or automate XML data bindings with gSOAP, you need:

<ul>
<li> The gSOAP package from <a href="http://www.genivia.com/Products/downloads.html"><tt>http://www.genivia.com/Products/downloads.html</tt></a> (select gSOAP toolkit standard edition from the list of software packages)
<div class="p"><!----></div>
</li>

<li> A C or C++ compiler.
<div class="p"><!----></div>
</li>

<li> You may want to install OpenSSL and the Zlib libraries to enable SSL (HTTPS) and compression. These libraries are available for most platforms and are often already installed.
<div class="p"><!----></div>
</li>
</ul>
The gSOAP software is self-contained, so there is no need to download any third-party
software (unless you want to use OpenSSL and the library is not already
installed, or if you need to rebuild the <i>soapcpp2</i> tool, see below).

<div class="p"><!----></div>
The gSOAP packages available from SourceForge include pre-build tools in the <i>gsoap/bin</i> directory:

<ul>
<li> The <i>wsdl2h</i> WSDL/schema importer and data binding mapper tool.
<div class="p"><!----></div>
</li>

<li> The <i>soapcpp2</i> stub/skeleton compiler and code generator.
<div class="p"><!----></div>
</li>
</ul>
Binaries of these two tools are included in the gSOAP package in
<i>gsoap/bin</i> for Windows, Linux, and Mac OS plarforms, see also the README
files in the package for more details.

<div class="p"><!----></div>
Although gSOAP tools are available in binary format for several platforms, the
code generated by these tools are all equivalent. This means that the generated
source codes can be transferred to other platforms and locally compiled.

<div class="p"><!----></div>
If you don't have the binaries or if you want to rebuild them, you need

<ul>
<li> A C compiler and Bison (or Yacc) to build <i>soapcpp2</i>.
<div class="p"><!----></div>
</li>

<li> A C compiler and Flex (or Lex) to build <i>soapcpp2</i>.
<div class="p"><!----></div>
</li>

<li> A C++ compiler to build <i>wsdl2h</i>.
<div class="p"><!----></div>
</li>
</ul>
Bison and Flex are preferred. Both are released under open source licenses that
are compatible with gSOAP's licenses.

<ul>
<li> Bison is available from <a href="http://www.gnu.org/software/bison"><tt>http://www.gnu.org/software/bison</tt></a>
<div class="p"><!----></div>
</li>

<li> Flex is available from <a href="http://flex.sourceforge.net"><tt>http://flex.sourceforge.net</tt></a>
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
The gSOAP engine is built as a library <i>libgsoap.a</i> and
<i>libgsoap++.a</i> with separate versions that support SSL. See the
<i>README.txt</i> instructions on how to build these libraries with the
platform-independent gSOAP package's autoconf and automake. Alternatively, you
can compile and link the engine's source code <i>stdsoap2.c</i> (or
<i>stdsoap2.cpp</i> for C++) directly with your code.

<div class="p"><!----></div>
The gSOAP packages contain numerous examples in the <i>samples</i> directory.
Run <i>make</i> to build the example applications. The examples are also meant
to demonstrate different features of gSOAP.
A streaming MTOM attachment server and client application
demonstrate efficient file exchanges in <i>samples/mtom-stream</i>. An SSL-secure Web
server application demonstrates the generation of dynamic content for Web
browsing and Web services functionality at the same time, see
<i>samples/webservice</i>. And much more.

<div class="p"><!----></div>
     <h3><a name="tth_sEc1.2">
1.2</a>&nbsp;&nbsp;<font color="#0000FF">Quick Start: Developing a Web Service Client Application</font></h3>

<div class="p"><!----></div>
The gSOAP tools minimize application adaptation efforts for building Web
Services by using a XML data binding for C and C++ implemented by 
advanced XML schema analyzers and source-to-source code generation tools.  The gSOAP <i>wsdl2h</i> tool imports one or more
WSDLs and XML schemas and generates a gSOAP header file with familiar C/C++ syntax to define the Web service operations
and the C/C++ data types. The gSOAP <i>soapcpp2</i>
compiler then takes this
header file and generates XML serializers for the data types (<i>soapH.h</i> and
<i>soapC.cpp</i>), the client-side stubs (<i>soapClient.cpp</i>), and server-side
skeletons (<i>soapServer.cpp</i>).

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> compiler can also generate WSDL definitions for
implementing a service from scratch, i.e.&nbsp;without defining a WSDL first. This
"closes the loop" in that it enables Web services development from WSDL or
directly from a set op C/C++ operations in a header file without the need for
users to analyze Web service details.

<div class="p"><!----></div>
You only need to follow a few steps to execute the tools from the command line
or Makefile (see also MSVC++ project examples in the <i>samples</i> directory
with tool integration in the MSVC++ IDE). For example, to generate code for the
calculator Web service, we run the <i>wsdl2h</i> tool from the
command line on the URL of the WSDL and use option <i>-o</i> to specify the
output file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h -o calc.h http://www.genivia.com/calc.wsdl</i>
</td></tr></table><br></span>
This generates the <i>calc.h</i> service definition header file with service
operation definitions and types for the operation's data. This
header file is then to be processed with <i>soapcpp2</i> to generate the stub and/or
skeleton code and XML serialization routines. The
<i>calc.h</i> file includes all documentation, so you can use Doxygen
(<a href="http://www.doxygen.org"><tt>http://www.doxygen.org</tt></a>) to automatically generate the documentation pages for
your development.

<div class="p"><!----></div>
The <i>wsdl2h</i>-generated service definitions header file also contains information on the use of the service, such as WS-Policy assertions when applicable.

<div class="p"><!----></div>
In this example we are developing a C++ API for the calculator service. By
default, gSOAP assumes you will use C++ with STL.  To build without STL, use option
<i>-s</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h -s -o calc.h http://www.genivia.com/calc.wsdl</i>
</td></tr></table><br></span>
To build a pure C application, use option <i>-c</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h -c -o calc.h http://www.genivia.com/calc.wsdl</i>
</td></tr></table><br></span>
<font color="#FF0000"><b>Important</b></font>: Visual Studio users shopuld make sure to compile all gSOAP
source files in C++ compilation mode. If you migrate to a project file
<i>.vcproj</i>, please set <tt>CompileAs="2"</tt> in your <i>.vcproj</i> file.
We have not yet generated the stubs for the C/C++ API. To do so, run the <i>soapcpp2</i> compiler:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -i -C -Iimport calc.h</i>
</td></tr></table><br></span>
Option <i>-i</i> (and alternatively option <i>-j</i>) indicates that we want C++ proxy and server objects that
include the client (and server) code, <i>-C</i> indicates client-side only files
(<i>soapcpp2</i> generates both client and server stubs and skeletons by
default). Option <i>-I</i> is needed to import the <i>stlvector.h</i> file from the <i>import</i> directory in the gSOAP package to support serialization of STL vectors.

<div class="p"><!----></div>
Suppose we develop a C++ client for the calculator service using <i>wsdl2h -o calc.h http://www.genivia.com/calc.wsdl</i> and <i>soapcpp2 -i -C calc.h</i>.

<div class="p"><!----></div>
We use the generated <i>soapcalcProxy</i> class and
<i>calc.nsmap</i> XML namespace mapping table to access the Web
service. The <i>soapcalcProxy</i> class is a proxy to invoke the
service:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapcalcProxy.h" <br />
#include "calc.nsmap" <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;calcProxy service; <br />
&nbsp;&nbsp;&nbsp;<b>double</b>&nbsp;result; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(service.add(1.0, 2.0, result) == SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;std::cout <tt>&lt;&lt;</tt> "The sum of 1.0 and 2.0 is " <tt>&lt;&lt;</tt> result <tt>&lt;&lt;</tt> std::endl; <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;service.soap_stream_fault(std::cerr); <br />
&nbsp;&nbsp;&nbsp;service.destroy(); // delete data and release memory <br />
}
</td></tr></table><br></i>
To complete the build, compile the code above and compile and link this with the generated <i>soapC.cpp</i>,
<i>soapcalcProxy.cpp</i>, and the run-time gSOAP engine <i>-lgsoap++</i> (or use source <i>stdsoap2.cpp</i> in case <i>libgsoap++.a</i> is not installed) with your code.

<div class="p"><!----></div>
Suppose we develop a client in C using <i>wsdl2h -c -o calc.h http://www.genivia.com/calc.wsdl</i> and <i>soapcpp2 -C calc.h</i>. In this case our code uses a simple C function call to invoke the service and we also need to explicitly delete data and the context with <i>soap_end</i> and <i>soap_free</i>:

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
#include "calc.nsmap" <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b> soap *soap = soap_new(); <br />
&nbsp;&nbsp;&nbsp;<b>double</b> result; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_ns__add(soap, 1.0, 2.0, &amp;result) == SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf("The sum of 1.0 and 2.0 is %lg<tt>\</tt>n", result); <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(soap, stderr); <br />
&nbsp;&nbsp;&nbsp;soap_end(soap); <br />
&nbsp;&nbsp;&nbsp;soap_free(soap); <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
The calculator example is fairly simple and used here to illustrate the
development process. The development process for large-scale XML applications
is similar. More extensive examples can be found in the <i>samples</i> directory
in the gSOAP package.

<div class="p"><!----></div>
     <h3><a name="tth_sEc1.3">
1.3</a>&nbsp;&nbsp;<font color="#0000FF">Quick Start: Developing a Web Service</font></h3>

<div class="p"><!----></div>
Developing a service application is easy too. We will use CGI here because it
is a simple mechanism. This is not the preferred deployment mechanism. Because
CGI is slow and stateless. Faster services can be developed as a stand-alone
gSOAP HTTP/HTTPS server (but see comments at the end of this section) or, as
preferred, the use of Apache module or IIS (included in the gSOAP package under
<i>gsoap/mod_gsoap</i> with instructions).

<div class="p"><!----></div>
Suppose we implement a CGI-based service that returns the time in GMT. The
Common Gateway Interface (CGI) is a simple mechanism to publish services on
your Web site.

<div class="p"><!----></div>
For this example we start with a gSOAP header file, <i>currentTime.h</i> which contains the service definitions. Such a file can be obtained from a WSDL using <i>wsdl2h</i> when a WSDL is available. When a WSDL is not available, you can define the service in C/C++ definitions in a newly created header file and let the gSOAP tools generate the source code and WSDL for you.

<div class="p"><!----></div>
Our <i>currentTime</i> service only has an output parameter, which is the
current time defined in our <i>currentTime.h</i> gSOAP service specification:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// File: currentTime.h <br />
//gsoap ns service name: currentTime <br />
//gsoap ns service namespace: urn:currentTime <br />
//gsoap ns service location: http://www.yourdomain.com/currentTime.cgi <br />
<b>int</b>&nbsp;ns__currentTime(time_t&amp; response);
</td></tr></table><br></i>
Note that we associate an XML namespace prefix <i>ns</i> and namespace name <i>urn:currentTime</i> with the service WSDL and SOAP/XML messages. The gSOAP tools
use a special convention for identifier names that are part of a namespace: a
namespace prefix (<i>ns</i> in this case) followed by a double underscore
<i>__</i>. This convention is used to resolve namespaces and to avoid name
clashes. The <i>ns</i> namespace prefix is bound to the <i>urn:currentTime</i>
namespace name with the <i>//gsoap</i> directive. The <i>//gsoap</i> directives
are used to set the properties of the service, in this case the name,
namespace, and location endpoint.

<div class="p"><!----></div>
The service implementation for CGI requires a <i>soap_serve</i> call on a soap context created with <i>soap_new</i>. The service operations are implemented as functions, which are called by the RPC dispatcher <i>soap_serve</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// File: currentTime.cpp <br />
#include "soapH.h" // include the generated declarations <br />
#include "currentTime.nsmap" // include the XML namespace mappings <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;// create soap context and serve one CGI-based request: <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_serve(soap_new()); <br />
}
<br />
<b>int</b>&nbsp;ns__currentTime(<b>struct</b>&nbsp;soap *soap, time_t&amp; response) <br />
{ <br />
&nbsp;&nbsp;&nbsp;response = time(0); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
Note that we pass the soap struct with the gSOAP context information to the
service routine. This can come in handy to determine properties of the connection
and to dynamically allocate data with <i>soap_malloc(soap, num_bytes)</i> that
will be automatically deleted when the service is finished.

<div class="p"><!----></div>
We run the <i>soapcpp2</i> compiler on the header file to generate the
server-side code:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -S currentTime.h</i>
</td></tr></table><br></span>
and then compile the CGI binary:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -o currentTime.cgi currentTime.cpp soapC.cpp soapServer.cpp stdsoap2.cpp</i>
</td></tr></table><br></span>
You will find <i>stdsoap2.cpp</i> in the <i>gsoap</i> dir. Or after installation
you can link with <i>libgsoap++</i> instead of using the <i>stdsoap2.cpp</i>
source:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -o currentTime.cgi currentTime.cpp soapC.cpp soapServer.cpp -lgsoap++</i>
</td></tr></table><br></span>
To activate the service, copy the <i>currentTime.cgi</i> binary to your
<i>bin-cgi</i> directory using the proper file permissions.

<div class="p"><!----></div>
The <i>soapcpp2</i> tool generated the WSDL definitions
<i>currentTime.wsdl</i>. You can use the WSDL to advertize your service.
You don't need to use this WSDL to develop a gSOAP client. You can use the
<i>currentTime.h</i> file with <i>soapcpp2</i> option <i>-C</i> to generate
client-side code.

<div class="p"><!----></div>
A convenient aspect of CGI is that it exchanges messages over standard
input/output. Therefore, you can run the CGI binary on the auto-generated
example request XML file to test your server:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  ./currentTime.cgi  &lt;  currentTime.currentTime.req.xml</i>
</td></tr></table><br></span>
and this displays the server response in SOAP XML.

<div class="p"><!----></div>
The above approach works also for C. Just use <i>soapcpp2</i> option <i>-c</i> in
addition to the <i>-S</i> option to generate ANSI C code. Of course, in C we use
pointers instead of references and the <i>currentTime.h</i> file should be
adjusted to use C-only types.

<div class="p"><!----></div>
A more elegant server implementation in C++ can be obtained by using the
<i>soapcpp2</i> option <i>-i</i> (or <i>-j</i>) to generate C++ client-side proxy and
server-side service objects as classes that you can use to build clients and
services in C++. The option removes the generation of <i>soapClient.cpp</i> and
<i>soapServer.cpp</i>, since these are no longer needed when we have classes
that implement the client and server logic:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -i -S currentTime.h</i>
</td></tr></table><br></span>
This generates <i>soapcurrentTimeService.h</i> and
<i>soapcurrentTimeService.cpp</i> files, as well as auxiliary files
<i>soapStub.h</i> (included by default by all codes) and <i>currentTime.nsmap</i>.

<div class="p"><!----></div>
Using the <i>currentTimeService</i> object we rewrite the CGI server as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// File: currentTime.cpp <br />
#include "soapcurrentTimeService.h" // include the proxy declarations <br />
#include "currentTime.nsmap" // include the XML namespace mappings <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;// create server and serve one CGI-based request: <br />
&nbsp;&nbsp;&nbsp;currentTimeService server; <br />
&nbsp;&nbsp;&nbsp;server.serve(); <br />
&nbsp;&nbsp;&nbsp;server.destroy(); <br />
}
<br />
<b>int</b>&nbsp;currentTimeService::currentTime(time_t&amp; response) <br />
{ <br />
&nbsp;&nbsp;&nbsp;response = time(0); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
Compile with
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -o currentTime.cgi currentTime.cpp soapC.cpp soapcurrentTimeService.cpp -lgsoap++</i>
</td></tr></table><br></span>
and install the binary as CGI. To install the CGI binary please consult your
Web server documentation on how to deploy CGI applications.

<div class="p"><!----></div>
To run the server as a stand-alone iterative (non-multithreaded) server on port 8080:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>while</b>&nbsp;(server.run(8080) != SOAP_TCP_ERROR) <br />
&nbsp;&nbsp;&nbsp;server.soap_stream_fault(std::cerr); <br />
</td></tr></table><br></i>

<div class="p"><!----></div>
To implement threaded services, please see Section&nbsp;<a href="#sec:mt">7.2.4</a>. These
stand-alone Web Services that handle multiple SOAP requests by spawning a
thread for each request. Thread pooling is also an option. The use of Apache
and IIS modules to deploy gSOAP services is preferred to ensure load balancing, access control, tracing, and so on.

<div class="p"><!----></div>
For more information on server-side service classes, see
Section&nbsp;<a href="#sec:object">7.2.7</a>. For more information on client-side proxy classes,
see Section&nbsp;<a href="#sec:proxy">7.1.4</a>.

<div class="p"><!----></div>
     <h3><a name="tth_sEc1.4">
1.4</a>&nbsp;&nbsp;<font color="#0000FF">Quick Start: XML Data Bindings</font></h3><a name="sec:mapping">
</a>

<div class="p"><!----></div>
Or in other words, how to map schemas (XSD files) to C/C++ bindings for
automatically reading and writing XML data.

<div class="p"><!----></div>
The XML C/C++ data binding in gSOAP provides and automated mechanism to encode
any C and C++ data type in XML (and decode XML back to C/C++ data). An XML
schema (XSD file) can be transformed into a set of C or C++ definitions
that can be readily incorporated into your application to manipulate XML with
much more ease than DOM or SAX. Essentially, each XML component definition in
an XML schema has a C/C++ data type representation that has equivalent type
properties. The advantage of this approach is immediately apparent when we look
at an XSD complexType that maps to a class:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>

<table>
<tr><td align="left">XSD </td><td align="left">C++ </td></tr>
<tr><td align="left">&lt;complexType name="Address"&#62;
</td><td align="left"><b>class</b>&nbsp;ns__Address </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;&lt;sequence&#62;
</td><td align="left">{ </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="name" type="string"/&#62;
</td><td align="left">&nbsp;&nbsp;&nbsp;std::string name; </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="home" type="tns:Location" minOccurs="0"/&#62;
</td><td align="left">&nbsp;&nbsp;&nbsp;ns__Location *home; </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="phone" type="unsignedLong"/&#62;
</td><td align="left">&nbsp;&nbsp;&nbsp;ULONG64 phone;  </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="dob" type="dateTime"/&#62;
</td><td align="left">&nbsp;&nbsp;&nbsp;time_t dob; </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;&lt;/sequence&#62; </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;&lt;attribute name="ID" type="int" use="required"/&#62;
</td><td align="left">&nbsp;&nbsp;&nbsp;@<b>int</b>&nbsp;ID; </td></tr>
<tr><td align="left">&lt;/complexType&#62;
</td><td align="left">}
</td></tr></table>

</td></tr></table><br></tt>
In this way, an automatic mapping
between XML elements of the XML schema and members of a class is created to
No DOM traversals and SAX events are needed.
In addition, the XML C/C++ data binding makes XML manipulation type safe. That
is, the type safety of C/C++ ensures that only valid XML documents can be
parsed and generated.

<div class="p"><!----></div>
The <i>wsdl2h</i> tool performs the mapping of WSDL and XML schemas to C and/or C++ automatically. The output of <i>wsdl2h</i> is an annotated header file that includes comments and documentation on the use of the C/C++ declarations in a SOAP/XML client/server or in a generic application for reading and writing XML using the auto-generated serializers.

<div class="p"><!----></div>
We will illustrate this further with an example. Suppose we have an XML document with a book record:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;book isbn="1234567890"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;title&#62;Farewell John Doe&lt;/title&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;publisher&#62;ABC's is our Name&lt;/publisher&#62; <br />
&lt;/book&#62;
</td></tr></table><br></tt>
An example XML schema that defines the book element and type could be
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;schema ...&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;element name="book"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;complexType&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;sequence&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="title" type="string" minOccurs="1"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="publisher" type="string" minOccurs="1"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/sequence&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;attribute name="isbn" type="unsignedLong" use="required"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/complexType&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/element&#62; <br />
&lt;/schema&#62;
</td></tr></table><br></tt>
Using <i>wsdl2h</i> we translate the XML schema that defines the book type and root element to a class definition:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b> book <br />
{ <br />
&nbsp;&nbsp;&nbsp;@ULONG64 isbn; <br />
&nbsp;&nbsp;&nbsp;std::string title; <br />
&nbsp;&nbsp;&nbsp;std::string publisher; <br />
}
</td></tr></table><br></i>
Note that annotations such as <i>@</i> are used to distinguish attributes
from elements. These annotations are gSOAP-specific and are handled by the <i>soapcpp2</i> tool to generate serializers for the data type(s) for reading and writing XML.

<div class="p"><!----></div>
The <i>soapcpp2</i> tool generates all
the necessary code to parse and generate XML for <i>book</i> objects. Validation
constraints such as <tt>minOccurs="1"</tt> and <tt>use="required"</tt> are included
in the generated code as checks.

<div class="p"><!----></div>
To write the XML representation of a book, we first create a <i>soap</i> engine context and use it with <i>soap_write_book</i> (generated by <i>soapcpp2</i>) to write the object in XML to standard output:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap *ctx = soap_new1(SOAP_XML_INDENT); // new context with option <br />
book bk; <br />
bk.isbn = 1234567890; <br />
bk.title = "Farewell John Doe"; <br />
bk.publisher = "ABC's is our Name"; <br />
<b>if</b>&nbsp;(soap_write_book(ctx, &amp;bk) != SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;<i>... error ...</i> <br />
soap_destroy(ctx); // clean up allocated class instances <br />
soap_end(ctx); // clean up allocated temporaries <br />
soap_free(ctx); // delete context
</td></tr></table><br></i>
The <i>ctx</i> gSOAP engine context (type <i><b>struct</b>&nbsp;soap</i>) controls settings
and holds state, such as XML formatting, (e.g. <i>SOAP_XML_INDENT</i>),
serialization options, current state, and I/O settings. Simply set the output
stream (std::ostream) <i>ctx</i><tt>-&gt;</tt><i>os</i> of the context to redirect the
content, e.g. to a file or string. Also, when serializing a graph rather than an XML tree (<i>SOAP_XML_TREE</i> option forces trees) the XML output conforms to SOAP encoding for object graphs based on id-ref, see Section&nbsp;<a href="#sec:bindings">7.5</a> for details.

<div class="p"><!----></div>
To read the XML representation from standard input into a book object, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap *ctx = soap_new1(SOAP_XML_STRICT); // new context with option <br />
book bk; <br />
<b>if</b>&nbsp;(soap_read_book(ctx, &amp;bk) != SOAP_OK)
&nbsp;&nbsp;&nbsp;<i>... error ...</i> <br />
<b>else</b><br />
&nbsp;&nbsp;&nbsp;cout &lt;&lt; bk.isbn &lt;&lt; ", " &lt;&lt; bk.title &lt;&lt; ", " &lt;&lt; bk.publisher &lt;&lt; endl; <br />
... <i>further use of bk</i> ...<br />
soap_destroy(ctx); // delete deserialized objects <br />
soap_end(ctx); // delete temporaries <br />
soap_free(ctx); // delete context
</td></tr></table><br></i>
Automatic built-in XML validation (enabled with <i>SOAP_XML_STRICT</i>)
ensures that data members are present so we can safely print them in this
example, thus ensuring consistency of data with the XML schema. Set the
<i>ctx</i><tt>-&gt;</tt><i>is</i> input stream to read from a file/string stream
instead of stdin.

<div class="p"><!----></div>
The <i>soap_destroy</i> and <i>soap_end</i> calls deallocate the deserialized
content, so use with care. In general, memory management is automatic in gSOAP
to avoid leaks.

<div class="p"><!----></div>
The above uses a very simple example schema. The gSOAP toolkit handles all XML schema constructs defined by the XML schema standard. The toolkit is also able to (de)serialize pointer-based C/C++
data structures (including cyclic graphs), structs/classes, unions, enums, STL
containers, and even special data types such as <i>struct tm</i>. Therefore, the toolkit works in two directions: from WSDL/schema to C/C++ and from C/C++ to WSDL/schema.

<div class="p"><!----></div>
The gSOAP toolkit also handles multiple schemas defined in multiple namespaces. Normally the namespace prefixes of XML namespaces are added to the C/C++ type
definitions to ensure type uniqueness. For example, if we would combine two
schemas in the same application where both schemas define a <i>book</i> object,
we need to resolve this conflict. In gSOAP this is done using namespace
prefixes, rather than C++ namespaces (research has pointed out that XML
namespaces are not equivalent to C++ namespaces). Thus, the <i>book</i> class
might actually be bound to an XML namespace and the class would be named
<i>ns__book</i>, where <i>ns</i> is bound to the corresponding namespace.

<div class="p"><!----></div>
The following options are available to control serialization:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap-&#62;encodingStyle = NULL; // to remove SOAP 1.1/1.2 encodingStyle<br />
soap_mode(soap, SOAP_XML_TREE); // XML without id-ref (no cycles!)<br />
soap_mode(soap, SOAP_XML_GRAPH); // XML with id-ref (including cycles)<br />
soap_set_namespaces(soap, <b>struct</b>&nbsp;Namespace *nsmap); //to set xmlns bindings
</td></tr></table><br></i>
Other flags can be used to format XML, see Section&nbsp;<a href="#sec:flags">9.12</a>.

<div class="p"><!----></div>
More information on XML databinding support for C and C++, see Section&nbsp;<a href="#sec:bindings">7.5</a>.

<div class="p"><!----></div>
     <h3><a name="tth_sEc1.5">
1.5</a>&nbsp;&nbsp;<font color="#0000FF">Feature Overview</font></h3>

<div class="p"><!----></div>
The highlights of gSOAP are:

<ul>
<li>Unique interoperability features: the tools generate type-safe SOAP marshalling
routines to (de)serialize native and user-defined C and C++ data structures.
<div class="p"><!----></div>
</li>

<li>
Support WSDL 1.1, WSDL 2.0, REST, SOAP 1.1, SOAP 1.2, SOAP RPC encoding style, and document/literal style.
gSOAP is one of the few SOAP toolkits that support the <b>full</b> range of SOAP 1.1
RPC encoding features including sparse multi-dimensional arrays and polymorphic
types. For example, a service operation with a base class parameter may accept
derived class instances from a client. Derived class instances keep their
identity through dynamic binding. The toolkit also supports <b>all XSD
1.0 and 1.1 schema type</b> constructs and has been tested against the W3C XML
Schema Patterns for Databinding Interoperability working group and of gSOAP
release 2.8.x passes all tests.
<div class="p"><!----></div>
</li>

<li>
Supports WS-Security, WS-Addressing, WS-ReliableMessaging, C14N exclusive
canonicalization. The protocols are implemented using code generation with
wsdl2h and soapcpp2. The gSOAP tools can be used to generate messaging
protocols for other WS-* protocols.
<div class="p"><!----></div>
</li>

<li>
gSOAP supports XML-RPC and RSS protocols. Examples are provided.
<div class="p"><!----></div>
</li>

<li> JSON support is included in the XML-RPC library to switch between XML-RPC
and JSON protocols. For more details, see the <i>samples/xml-rpc-json</i> folder in the package.
<div class="p"><!----></div>
</li>

<li>
The <i>wsdl2h</i> tool supports WS-Policy. Policy assertions are included in
the generated service description header file with recommendations and usage
hints.
<div class="p"><!----></div>
</li>

<li>
gSOAP supports MIME (SwA), DIME, and MTOM attachments and has streaming
capabilities to direct the data stream to/from resources.
gSOAP is the only toolkit that supports <em>streaming</em> MIME, DIME, and MTOM
attachment transfers, which allows you to exchange binary data of practically
unlimited size in the fastest possible way (streaming) while ensuring the
usefulness of XML interoperability.
<div class="p"><!----></div>
</li>

<li>
gSOAP supports SOAP-over-UDP.
<div class="p"><!----></div>
</li>

<li>
gSOAP supports IPv4 and IPv6.
<div class="p"><!----></div>
</li>

<li>
gSOAP supports Zlib deflate and gzip compression (for HTTP, TCP/IP, and XML file storage).
<div class="p"><!----></div>
</li>

<li>
gSOAP supports SSL (HTTPS) using OpenSSL and optionally using GNUTLS.
<div class="p"><!----></div>
</li>

<li>
gSOAP supports HTTP/1.0, HTTP/1.1 keep-alive, chunking, basic authentication, and digest authentication using a plugin.
<div class="p"><!----></div>
</li>

<li>
gSOAP supports SOAP one-way messaging.
<div class="p"><!----></div>
</li>

<li>
The schema-specific XML pull parser is fast and efficient and does not require intermediate data storage for
demarshalling to save space and time.
<div class="p"><!----></div>
</li>

<li>
The <i>soapcpp2</i> compiler includes a WSDL and schema generator for convenient
Web Service publishing.
<div class="p"><!----></div>
</li>

<li>
The <i>soapcpp2</i> compiler generates sample input and output messages
for verification and testing (before writing any code). An option (<i>-T</i>)
can be used to automatically implement echo message services for testing.
<div class="p"><!----></div>
</li>

<li>
The <i>wsdl2h</i> tool converts WSDL and XSD files to gSOAP header files for automated client and server development.
<div class="p"><!----></div>
</li>

<li>
Generates source code for stand-alone Web Services and client applications.
<div class="p"><!----></div>
</li>

<li>
Ideal for small devices such as Palm OS, Symbian, Pocket PC, because the memory footprint is small.
<div class="p"><!----></div>
</li>

<li>
Ideal for building web services that are compute-intensive and are therefore best written in C and C++.
<div class="p"><!----></div>
</li>

<li>
Platform independent: Windows, Unix, Linux, Mac OS X, Pocket PC, Palm OS, Symbian, VXWorks, etc.
<div class="p"><!----></div>
</li>

<li>
Supports serializing of application's native C and C++ data structures, which allows you to save and load XML serialized data structures to and from files.
<div class="p"><!----></div>
</li>

<li>
Selective input and output buffering is used to increase efficiency, but full message buffering to determine HTTP message length
is not used. Instead, a three-phase serialization method is used to determine message length. As a result, large data sets
such as base64-encoded images can be transmitted with or without DIME attachments by small-memory devices such as PDAs.
<div class="p"><!----></div>
</li>

<li>
Supports C++ single class inheritance, dynamic binding, overloading, arbitrary pointer structures such as lists, trees, graphs,
cyclic graphs, fixed-size arrays, (multi-dimensional) dynamic arrays, enumerations, built-in XSD Schema types including
base64Binary encoding, and hexBinary encoding.
<div class="p"><!----></div>
</li>

<li>
No need to rewrite existing C/C++ applications for Web service deployment. However, parts of an application that use unions,
pointers to sequences of elements in memory, and <i><b>void</b>*</i> need to be modified, but <b>only</b> if the data structures that
adopt them are required to be serialized or deserialized as part of a service operation invocation.
<div class="p"><!----></div>
</li>

<li>
Three-phase marshalling: 1) analysis of pointers, single-reference, multi-reference, and cyclic data structures, 2) HTTP
message-length determination, and 3) serialization as per SOAP 1.1 encoding style or user-defined encoding styles.
<div class="p"><!----></div>
</li>

<li>
Two-phase demarshalling: 1) SOAP parsing and decoding, which involves the reconstruction of multi-reference and cyclic data
structures from the payload, and 2) resolution of "forward" pointers (i.e. resolution of the forward <tt>href</tt> attributes in SOAP).
<div class="p"><!----></div>
</li>

<li>
Full and customizable SOAP Fault processing (client receive and service send).
<div class="p"><!----></div>
</li>

<li>
Customizable SOAP Header processing (send and receive), which for example enables easy transaction processing for the service to
keep state information.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
 <h2><a name="tth_sEc2">
2</a>&nbsp;&nbsp;<font color="#0000FF">Notational Conventions</font></h2>

<div class="p"><!----></div>
The typographical conventions used by this document are:

<dl compact="compact">
 <dt><b><span class="roman"><i>Sans serif or italics font</i></b></dt>
	<dd> denotes C and C++ source code, file names, and shell/batch commands.</span></dd>
 <dt><b><i><b>Bold font</b></i></b></dt>
	<dd> denotes C and C++ keywords.</dd>
 <dt><b><tt>Courier font</tt></b></dt>
	<dd> denotes HTTP header content, HTML, XML, XML Schema content and WSDL content.</dd>
 <dt><b><span class="roman"><font size="+1"><span class="roman">[</span></font>Optional<font size="+1"><span class="roman">]</span></font></b></dt>
	<dd> denotes an optional construct.</span></dd>
</dl>

<div class="p"><!----></div>
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in RFC-2119.

<div class="p"><!----></div>
 <h2><a name="tth_sEc3">
3</a>&nbsp;&nbsp;<font color="#0000FF">Differences Between gSOAP Versions 2.4 (and Earlier) and 2.5</font></h2>

<div class="p"><!----></div>
To comply with WS-I Basic Profile 1.0a, gSOAP 2.5 and higher adopts SOAP document/literal by default.
There is no need for concern, because the WSDL parser <i>wsdl2h</i> automatically takes care of the differences when you provide a WSDL document, because SOAP RPC encoding, literal, and document style are supported.
A new soapcpp2 compiler option was added <i>-e</i> for backward compatibility with gSOAP 2.4 and earlier to adopt SOAP RPC encoding by default in case you want to develop a service that uses SOAP encoding. You can also use the gSOAP <i>soapcpp2</i> compiler directives to specify SOAP encoding for individual operarations, when desired.

<div class="p"><!----></div>
 <h2><a name="tth_sEc4">
4</a>&nbsp;&nbsp;<font color="#0000FF">Differences Between gSOAP Versions 2.1 (and Earlier) and 2.2</font></h2>

<div class="p"><!----></div>
You should read this section only if you are upgrading from gSOAP 2.1 to 2.2 and later.

<div class="p"><!----></div>
Run-time options and flags have been changed to enable separate recv/send
settings for transport, content encodings, and mappings.  The flags are divided
into four classes: transport (IO), content encoding (ENC), XML marshalling
(XML), and C/C++ data mapping (C).  The old-style flags <i>soap_disable_X</i>
and <i>soap_enable_X</i>, where <i>X</i> is a particular feature, are
deprecated.  See Section&nbsp;<a href="#sec:flags">9.12</a> for more details.

<div class="p"><!----></div>
 <h2><a name="tth_sEc5">
5</a>&nbsp;&nbsp;<font color="#0000FF">Differences Between gSOAP Versions 1.X and 2.X</font></h2>

<div class="p"><!----></div>
You should read this section only if you are upgrading from gSOAP 1.X to 2.X.

<div class="p"><!----></div>
gSOAP versions 2.0 and later have been rewritten based on versions 1.X.
gSOAP 2.0 and later is thread-safe, while 1.X is not.
All files in the gSOAP 2.X distribution are renamed to avoid confusion with gSOAP version 1.X files:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>gSOAP 1.X</b></font>	</td><td align="left"><font color="#FF0000"><b>gSOAP 2.X</b></font> </td></tr>
<tr><td align="left">soapcpp		</td><td align="left">soapcpp2 </td></tr>
<tr><td align="left">soapcpp.exe	</td><td align="left">soapcpp2.exe </td></tr>
<tr><td align="left">stdsoap.h	</td><td align="left">stdsoap2.h </td></tr>
<tr><td align="left">stdsoap.c	</td><td align="left">stdsoap2.c </td></tr>
<tr><td align="left">stdsoap.cpp	</td><td align="left">stdsoap2.cpp </td></tr></table>

</td></tr></table><br></span>
Changing the version 1.X application codes to accommodate gSOAP 2.X does not require a significant amount of recoding.
The change to gSOAP 2.X affects all functions defined in <i>stdsoap2.c[pp]</i> (the gSOAP runtime context API) and the functions in the
sources generated by the gSOAP <i>soapcpp2</i> compiler (the gSOAP RPC+marshalling API).
Therefore, clients and services developed with gSOAP 1.X need to be modified to accommodate a change in the calling convention used in 2.X:
In 2.X, <b>all</b> gSOAP functions (including the service operation proxy routines) take an additional parameter which is an instance of the gSOAP runtime
context that includes file descriptors, tables, buffers, and flags.
This additional parameter is <b>always</b> the first parameter of any gSOAP function.

<div class="p"><!----></div>
The gSOAP runtime context is stored in a <i><b>struct</b>&nbsp;soap</i> type. A <i><b>struct</b></i> was chosen to support application development in
C without the need for a separate gSOAP implementation.  An object-oriented approach with a class for the gSOAP runtime context would have prohibited the implementation of pure C applications.
Before a client can invoke service operations or before a service can accept requests, a runtime context needs to be allocated and
initialized.
Three new functions are added to gSOAP 2.X:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>soap_init(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Initializes a context (required only once) </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap *soap_new()</i> </td><td align="left">Allocates, initializes, and returns a pointer to a runtime context </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap *soap_copy(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Allocates a new runtime context and copies contents of
the context such that the new environment does not share any data
with the original context </td></tr></table>

</td></tr></table><br></span>
A context can be reused as many times as necessary and does not need to be
reinitialized in doing so. A dynamically allocated context is deallocated
with <i>soap_free</i>.

<div class="p"><!----></div>
A new context is only required for each new thread to guarantee exclusive access
to a new runtime context by each thread.
For example, the following code stack-allocates the runtime context which is used for multiple service operation calls:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); // initialize runtime context <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__method1(&amp;soap, ...); // make a remote call <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__method2(&amp;soap, ...); // make another remote call <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_destroy(&amp;soap); // remove deserialized class instances (C++ only) <br />
&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); // clean up and remove deserialized data <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); // detach context (last use and no longer in scope)<br />
&nbsp;&nbsp;&nbsp;... <br />
}
</td></tr></table><br></i>
The runtime context can also be heap allocated:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap *soap; <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap = soap_new(); // allocate and initialize runtime context <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap) // couldn't allocate: stop <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__method1(soap, ...); // make a remote call <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__method2(soap, ...); // make another remote call <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_destroy(soap); // remove deserialized class instances (C++ only) <br />
&nbsp;&nbsp;&nbsp;soap_end(soap); // clean up and remove deserialized data <br />
&nbsp;&nbsp;&nbsp;soap_free(soap); // detach and free runtime context <br />
}
</td></tr></table><br></i>
A service needs to allocate and initialize an context before calling <i>soap_serve</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_serve(&amp;soap); <br />
}
</td></tr></table><br></i>
Or alternatively:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_serve(soap_new()); <br />
}
</td></tr></table><br></i>
The <i>soap_serve</i> dispatcher handles one request or multiple requests when HTTP keep-alive is enabled (with the <i>SOAP_IO_KEEPALIVE</i> flag see Section&nbsp;<a href="#sec:keepalive">19.11</a>).

<div class="p"><!----></div>
A service can use multi-threading to handle requests while running some other code that invokes service operations:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap1, soap2; <br />
&nbsp;&nbsp;&nbsp;pthread_t tid; <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap1); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_bind(&amp;soap1, host, port, backlog)  &lt;  0) exit(1); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_accept(&amp;soap1)  &lt;  0) exit(1); <br />
&nbsp;&nbsp;&nbsp;pthread_create(&amp;tid, NULL, (<b>void</b>*(*)(<b>void</b>*))soap_serve, (<b>void</b>*)&amp;soap1); <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap2); <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__method(&amp;soap2, ...); // make a remote call <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_end(&amp;soap2); <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;pthread_join(tid, NULL); // wait for thread to terminate <br />
&nbsp;&nbsp;&nbsp;soap_end(&amp;soap1); // release its data <br />
}
</td></tr></table><br></i>
In the example above, two runtime contexts are required.
In comparison, gSOAP 1.X statically allocates the runtime context, which prohibits multi-threading (only one thread can invoke
service operations and/or accept requests due to the single runtime context).

<div class="p"><!----></div>
Section&nbsp;<a href="#sec:mt">7.2.4</a> presents a multi-threaded stand-alone Web Service that handles multiple SOAP requests by spawning a thread for each request.

<div class="p"><!----></div>
 <h2><a name="tth_sEc6">
6</a>&nbsp;&nbsp;<font color="#0000FF">Interoperability</font></h2>

<div class="p"><!----></div>
gSOAP interoperability has been verified with the following SOAP implementations and toolkits:

<div class="p"><!----></div>

<blockquote>Apache 2.2 <br />
Apache Axis <br />
ASP.NET <br />
Cape Connect <br />
Delphi <br />
easySOAP++ <br />
eSOAP <br />
Frontier <br />
GLUE <br />
Iona XMLBus <br />
kSOAP <br />
MS SOAP <br />
Phalanx <br />
SIM <br />
SOAP::Lite <br />
SOAP4R <br />
Spray <br />
SQLData <br />
WCF <br />
White Mesa <br />
xSOAP <br />
ZSI <br />
4S4C <br />
</blockquote>

<div class="p"><!----></div>
 <h2><a name="tth_sEc7">
7</a>&nbsp;&nbsp;<font color="#0000FF">Quick User Guide</font></h2>

<div class="p"><!----></div>
This user guide offers a quick way to get started with gSOAP.  This section
requires a basic understanding of the SOAP protocol and some familiarity
with C and/or C++. In principle, SOAP clients and SOAP Web services can be
developed in C and C++ with the gSOAP <i>soapcpp2</i> compiler without a detailed understanding
of the SOAP protocol when gSOAP client-server applications are built as an
ensamble and only communicate within this group (i.e.&nbsp;meaning that you don't
have to worry about interoperability with other SOAP implementations).  This
section is intended to illustrate the implementation of gSOAP Web services and
clients that connect to and interoperate with other SOAP implementations such
as Apache Axis, SOAP::Lite, and .NET.  This requires some details of the SOAP
and WSDL protocols to be understood.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc7.1">
7.1</a>&nbsp;&nbsp;<font color="#0000FF">How to Build SOAP/XML Clients</font></h3><a name="sec:client">
</a>

<div class="p"><!----></div>
In general, the implementation of a SOAP client application requires a <em>
stub</em> (also called <em>service proxy</em>) for each service operation that the client invokes. The primary stub's responsibility is to marshall the parameter data,
send the request with the parameters to the designated SOAP service over the
wire, to wait for the
response, and to demarshall the parameter data of the response when it arrives. The client
application invokes the stub routine for a service operation as if it would invoke
a local function. To write a stub routine in C or C++ by hand is a tedious task,
especially if the input and/or output parameters of a service operation contain
elaborate data structures such as objects, structs, containers, arrays, and pointer-linked graph structures. Fortunately, the
gSOAP <i>wsdl2h</i> WSDL parser tool and <i>soapcpp2</i> stub/skeleton and serialization code generator tool automate the
development of SOAP/XML Web service client and server applications.

<div class="p"><!----></div>
The <i>soapcpp2</i> tool generates the necessary gluing code (also called stubs and skeletons) to build web service clients and services. The input to the <i>soapcpp2</i>
tool consists of an service definition-annotated C/C++ <b>header file</b>. The
header file can be generated from a WSDL (Web Service Description Language)
documentation of a service with the gSOAP <i>wsdl2h</i> WSDL parser tool.

<div class="p"><!----></div>
Consider the following command (entered at the Linux/Unix/Windows command line prompt):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h -o calc.h http://www.genivia.com/calc.wsdl</i>
</td></tr></table><br></span>
This generates the file Web service description <i>calc.h</i> in an annotated C++ header file.
The WSDL specification (possibly consisting of multiple imported WSDL files and XSD schema files) is mapped to C++ using C++ databindings for
SOAP/XML. The generated header file contains data types and messages to operate
the service, and meta information related to WSDL and XML schemas.

<div class="p"><!----></div>
To generate a service definition header file to develop a pure C client application, use the <i>-c</i> option:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h -c -o calc.h http://www.genivia.com/calc.wsdl</i>
</td></tr></table><br></span>
For more details on the WSDL parser and its options, see&nbsp;<a href="#sec:wsdlin">8</a>.

<div class="p"><!----></div>
The service definition <i>calc.h</i> header file is further processed by the
gSOAP <i>soapcpp2</i> compiler to generate the gluing code's logic to invoke
the Web service from a client.

<div class="p"><!----></div>
Looking into the file <i>calc.h</i> we see that the SOAP service methods are
specified as <b>function prototypes</b>. For example, the <i>add</i> function to add two double floats:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns2__add(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&amp; result);
</td></tr></table><br></i>
The <i>ns2__add</i> function uses an XML namespace prefix to distinguish it
from operations defined in other namespaces, thus preventing name clashes. The
convention to add an XML namespace prefix to the names of operations, types,
and <i><b>struct</b></i> and <i><b>class</b></i> members is universally used by the gSOAP
tools and automatically created by <i>wsdl2h</i>, but it is not mandatory when
translating existing C/C++ types and operations to web services. Thus, the
prefix notation can be omitted from type names defined in an header file with
to run <i>soapcpp2</i> to create clients and services that exchange existing
(i.e.&nbsp;application-native) data types.

<div class="p"><!----></div>
These function prototypes are translated by the gSOAP <i>soapcpp2</i> tool to stubs and proxies for remote calls:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><i>soapStub.h</i> </td><td align="left">annotated copy of the input definitions </td></tr>
<tr><td align="left"><i>soapH.h</i> </td><td align="left">serializers </td></tr>
<tr><td align="left"><i>soapC.cpp</i> </td><td align="left">serializers </td></tr>
<tr><td align="left"><i>soapClient.cpp</i> </td><td align="left">client calling stubs
</td></tr></table>

</td></tr></table><br></span>
Thus, the logic of the generated stub routines allow C and
C++ client applications to seamlessly interact with existing SOAP Web services as illustrated by the client code example in the next section.

<div class="p"><!----></div>
The input and output parameters of a SOAP service operation may be primitive data
types or complex compound data types such as containers and pointer-based linked data structures. These are defined in the header file that is either generated by the WSDL parser or specified by hand.
The gSOAP <i>soapcpp2</i> tool automatically generates <b>
XML serializers</b> and <b>XML deserializers</b> for the data types to enable the generated
stub routines to encode and decode the contents of the parameters of the service operations 
in SOAP/XML.

<div class="p"><!----></div>
Note that the gSOAP <i>soapcpp2</i> tool also generates <b>skeleton</b>
routines <i>soapServer.cpp</i> for each of the service operations specified in the header file. The
skeleton routines
can be readily used to implement one or more of the service operations in a new
SOAP Web service. These skeleton routines are not used for building SOAP
clients in C++, although they can be used to build mixed SOAP client/server
applications (peer applications).

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.1">
7.1.1</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4><a name="sec:example1">
</a>

<div class="p"><!----></div>
The <i>add</i> service operation (declared in the <i>calc.h</i> file obtained
with the <i>wsdl2h</i> tool in the previous section) adds two float values.
The WSDL description of the service provides the endpoint to invoke the service operations and the XML namespace used by the operations:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left">Endpoint URL: </td><td align="left"><tt>http://websrv.cs.fsu.edu/&nbsp;engelen/calcserver.cgi</tt> </td></tr>
<tr><td align="left">XML namespace: </td><td align="left"><tt>urn:calc</tt>
</td></tr></table>

</td></tr></table><br></span>
Each service operation has a SOAP action, which is an optional string to
identify the operation (mainly used with WS-Addressing), an operation request
message and a response message. The request and response messages for SOAP
RPC-encoded services are simply represented by C functions with input and
output parameters. For the <i>add</i> operation, the SOAP binding details are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left">SOAP style: </td><td align="left">RPC </td></tr>
<tr><td align="left">SOAP encoding: </td><td align="left">encoded </td></tr>
<tr><td align="left">SOAP action: </td><td align="left"><tt>""</tt> (empty string)
</td></tr></table>

</td></tr></table><br></span>
This information is translated to the <i>wsdl2h</i>-generated header file with the service definitions.
The <i>calc.h</i> header file for C++ generated by <i>wsdl2h</i> contains the following directives and declarations:
(the actual contents may vary depending on the release version and the options used to control the output):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns2 service name:       calc
//gsoap ns2 service type:       calcPortType
//gsoap ns2 service port:       http://websrv.cs.fsu.edu/&nbsp;engelen/calcserver.cgi <br />
//gsoap ns2 service namespace:  urn:calc <br />
<br />
//gsoap ns2 service method-protocol:    add SOAP <br />
//gsoap ns2 service method-style:       add rpc <br />
//gsoap ns2 service method-encoding:    add http://schemas.xmlsoap.org/soap/encoding/ <br />
//gsoap ns2 service method-action:      add "" <br />
<b>int</b>&nbsp;ns2__add(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&amp; result);
</td></tr></table><br></i>
The other calculator operations are similar and elided here for clarity.

<div class="p"><!----></div>
The <i>//gsoap</i> directives are required for the
<i>soapcpp2</i> tool to generate code that is compliant to the SOAP protocol. For this service the SOAP protocol with the common "RPC encoding style" is used. For <i>//gsoap</i> directive details, see Section&nbsp;<a href="#sec:directives">19.2</a>.

<div class="p"><!----></div>
The service operations are declared as
function prototypes, with all non-primitive parameter types needed by the
operation declared in the header file (all parameter types are primitive in
this case).

<div class="p"><!----></div>
The calculator <i>add</i> opertion takes two double floats <i>a</i> and <i>b</i>,
and returns the sum in <i>result</i>. By convention, <b>all parameters are input
parameters except the last</b>. The last parameter is always the output parameter.
A <i><b>struct</b></i> or <i><b>class</b></i> is used to wrap multiple output parameters, see
also Section&nbsp;<a href="#sec:multiple">7.1.9</a>. This last parameter must be a pointer or
reference. By contrast, the input parameters support pass by value or by
pointer, but not pass by C++ reference.

<div class="p"><!----></div>
The function prototype associated with a service operation always returns an
<i><b>int</b></i>. The value indicates success (<i>0</i> or equivalently
<i>SOAP_OK</i>) or failure (any nonzero value). See Section&nbsp;<a href="#sec:errcodes">10.2</a>
for the nonzero error codes. 

<div class="p"><!----></div>
The role of the namespace prefix (<i>ns2__</i>) in the service operation name in the
function prototype declaration is discussed in detail in&nbsp;<a href="#sec:namespace">7.1.2</a>.
Basically, a namespace prefix is added to a function name or type name with a <b>pair of underscores</b>,
as in <i>ns2__add</i>, where <i>ns2</i> is the
namespace prefix and <i>add</i> is the service operation name. This mechanism ensures uniqueness of operations and types associated with a service.

<div class="p"><!----></div>
It is strongly recommended to set the namespace prefix to a name of your
choice. This avoids problems when running <i>wsdl2h</i> on multiple WSDLs where
the sequence of prefixes <i>ns1</i>, <i>ns2</i>, and so on are arbitrarily
assigned to the services. To choose a prefix name for all the operations and types of a service, say prefix <i>c__</i> for the calculator service, add the following line to <i>typemap.dat</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
c = "urn:calc"
</td></tr></table><br></tt>
and rerun <i>wsdl2h</i>. The <i>typemap.dat</i> configures <i>wsdl2h</i> to use
specific bindings and data types for services. The result is that <i>c__add</i> is used to uniquely identify the operation rather than the more arbitrary name <i>ns2__add</i>.

<div class="p"><!----></div>
Note on the use of underscores in names: a single
underscore in an identifier name will be translated into a dash in XML, because
dashes are more frequently used in XML compared to underscores, see
Section&nbsp;<a href="#sec:idtrans">10.3</a>.

<div class="p"><!----></div>
Next, the gSOAP <i>soapcpp2</i> tool is invoked from the command line to process the <i>calc.h</i> service definitions:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 calc.h</i>
</td></tr></table><br></span>
The tool generates the stub routines for the service operations.
Stub routines can be invoked
by a client program to invoke the remote service operations.
The interface of the generated stub routine is identical to the function prototype in the <i>calc.h</i> service defintion file, but with additional parameters to pass the gSOAP engine's runtime context <i>soap</i>, an endpoint URL (or NULL for the default), and a SOAP action (or NULL for the default):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;soap_call_c__add(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*URL, <b>char</b>&nbsp;*action, <b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&amp; result);
</td></tr></table><br></i>
This stub routine is saved in <i>soapClient.cpp</i>. The file <i>soapC.cpp</i>
contains the <b>serializer</b> and <b>deserializer</b> routines for the data
types used by the stub. You can use option <i>-c</i> for the <i>soapcpp2</i> tool to
generate pure C code, when needed.

<div class="p"><!----></div>
Note: the <i>soap</i> parameter must be a valid pointer to a gSOAP runtime
context. The <i>URL</i> can be set to override the default endpoint address (the endpoint defined by the WSDL).
The <i>action</i> parameter can be set to override the default SOAP action.

<div class="p"><!----></div>
The following example C/C++ client program uses the stub:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include <tt>"soapH.h"</tt> // include all interfaces (library and generated) <br />
#include <tt>"calc.nsmap"</tt> // import the generated namespace mapping table <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>double</b>&nbsp;sum; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; // the gSOAP runtime context <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); // initialize the context (only once!) <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_c__add(&amp;soap, NULL, NULL, 1.0, 2.0, &amp;sum) == SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;std::cout  &lt;&lt;  "Sum = "  &lt;&lt;  sum  &lt;&lt;  std::endl; <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;// an error occurred <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // display the SOAP fault message on the stderr stream <br />
&nbsp;&nbsp;&nbsp;soap_destroy(&amp;soap); // delete deserialized class instances (for C++) <br />
&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); // remove deserialized data and clean up <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); // detach the gSOAP context <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
}
</td></tr></table><br></i>
The call returns <i>SOAP_OK</i> (zero) on success and a nonzero error on
failure.  When an error occurred the fault is displayed with the
<i>soap_print_fault</i> function. Use <i>soap_sprint_fault(<b>struct</b>&nbsp;soap*,
<b>char</b>&nbsp;*buf, size_t len)</i> to print the error to a string, and use <i>soap_stream_fault(<b>struct</b>&nbsp;soap*, std::ostream&amp;)</i> to send it to a stream (C++ only).

<div class="p"><!----></div>
The following functions can be used to explicitly setup a gSOAP runtime context (<i><b>struct</b>&nbsp;soap</i>):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>soap_init(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Initializes a runtime context </td></tr>
<tr><td align="left"><i>soap_init1(<b>struct</b>&nbsp;soap *soap, soap_mode iomode)</i> </td><td align="left">Initializes a runtime context and set in/out mode flags </td></tr>
<tr><td align="left"><i>soap_init2(<b>struct</b>&nbsp;soap *soap, soap_mode imode, soap_mode omode)</i> </td><td align="left">Initializes a runtime context and set in/out mode flags </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap *soap_new()</i> </td><td align="left">Allocates, initializes, and returns a pointer to a runtime context </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap *soap_new1(soap_mode iomode)</i> </td><td align="left">Allocates, initializes, and returns a pointer to a runtime context and set in/out mode flags </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap *soap_new2(soap_mode imode, soap_mode omode)</i> </td><td align="left">Allocates, initializes, and returns a pointer to a runtime context and set in/out mode flags </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap *soap_copy(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Allocates a new runtime context and copies a context (deep copy, i.e.&nbsp;the new context does not share any data with the other context) </td></tr>
<tr><td align="left"><i>soap_done(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Reset, close communications, and remove callbacks </td></tr>
<tr><td align="left"><i>soap_free(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Reset and deallocate the context created with <i>soap_new</i> or <i>soap_copy</i> </td></tr></table>

</td></tr></table><br></span>
A runtime context can be reused as many times as necessary for client-side remote calls and does not need to be reinitialized in doing so.
A new context is required for each new thread to guarantee exclusive access
to runtime context by threads.  Also the use of any client calls within an active service method requires a new context.

<div class="p"><!----></div>
The <i>soapcpp2</i> code generator tool also generates a service proxy class for C++ client applications (and service objects for server applications) with the <i>-i</i> (or <i>-j</i>) option:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -i calc.h</i>
</td></tr></table><br></span>
The proxy is defined in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><i>soapcalcProxy.h</i> </td><td align="left">client proxy class </td></tr>
<tr><td align="left"><i>soapcalcProxy.cpp</i> </td><td align="left">client proxy class
</td></tr></table>

</td></tr></table><br></span>
Note: without the <i>-i</i> option only old-style service proxies and objects
are generated, which are less flexible and no longer recommended. Use <i>-j</i>
as an alternative to <i>-i</i> to generate classes with the same functionality,
but that are not inherited from <i><b>struct</b>&nbsp;soap</i> and use a pointer to a
<i><b>struct</b>&nbsp;soap</i> engine context that can be shared with other proxy and
service class instances. This choice is also important when services are chained, see Section&nbsp;<a href="#sec:chaining">7.2.8</a>.

<div class="p"><!----></div>
The generated C++ proxy class initializes the gSOAP runtime context and offers the service interface as a collection of methods:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include <tt>"soapcalcProxy.h"</tt> // get proxy <br />
#include <tt>"calc.nsmap"</tt> // import the generated namespace mapping table <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;calcProxy calc(SOAP_XML_INDENT); <br />
&nbsp;&nbsp;&nbsp;<b>double</b>&nbsp;sum; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(calc.add(1.0, 2.0, sum) == SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;std::cout  &lt;&lt;  "Sum = "  &lt;&lt;  sum  &lt;&lt;  std::endl; <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;calc.soap_stream_fault(std::cerr); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;calc.error; // nonzero when error <br />
}
</td></tr></table><br></i>
The proxy class is derived from the gSOAP runtime context structure
<i><b>struct</b>&nbsp;soap</i> and thus inherits (option <i>-i</i>) all state information
of the runtime. The proxy constructor takes context mode parameters to initialize the context, e.g.&nbsp;<i>SOAP_XML_INDENT</i> in this example.

<div class="p"><!----></div>
The code is compiled and linked with <i>soapcalcProxy.cpp</i>, <i>soapC.cpp</i>,
and <i>stdsoap2.cpp</i> (or use <i>libgsoap++.a</i>).

<div class="p"><!----></div>
The proxy class name is extracted from the WSDL content and may not always be in a short format. Feel free to change the entry
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns2 service name: calc
</td></tr></table><br></i>
and rerun <i>soapcpp2</i> to generate code that uses the new name.

<div class="p"><!----></div>
When the example client application is invoked, a SOAP request is performed:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
POST /&nbsp;engelen/calcserver.cgi HTTP/1.1 <br />
Host: websrv.cs.fsu.edu <br />
User-Agent: gSOAP/2.7 <br />
Content-Type: text/xml; charset=utf-8 <br />
Content-Length: 464 <br />
Connection: close <br />
SOAPAction: "" <br />
 <br />
&lt;?xml version="1.0" encoding="UTF-8"?&#62; <br />
&lt;SOAP-ENV:Envelope <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsd="http://www.w3.org/2001/XMLSchema" <br />
&nbsp;&nbsp;&nbsp;xmlns:c="urn:calc"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;c:add&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;a&#62;1&lt;/a&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;b&#62;2&lt;/b&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/c:add&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/SOAP-ENV:Body&#62; <br />
&lt;/SOAP-ENV:Envelope&#62;
</td></tr></table><br></tt>
The SOAP response message:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
HTTP/1.1 200 OK <br />
Date: Wed, 05 May 2010 16:02:21 GMT <br />
Server: Apache/2.0.52 (Scientific Linux) <br />
Content-Length: 463 <br />
Connection: close <br />
Content-Type: text/xml; charset=utf-8 <br />
 <br />
&lt;?xml version="1.0" encoding="UTF-8"?&#62; <br />
&lt;SOAP-ENV:Envelope <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsd="http://www.w3.org/2001/XMLSchema" <br />
&nbsp;&nbsp;&nbsp;xmlns:ns="urn:calc"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;ns:addResponse&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;result&#62;3&lt;/result&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/ns:addResponse&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/SOAP-ENV:Body&#62; <br />
&lt;/SOAP-ENV:Envelope&#62;
</td></tr></table><br></tt>
A client can invoke a sequence of service operations:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include <tt>"soapcalcProxy.h"</tt> // get proxy <br />
#include <tt>"calc.nsmap"</tt> // import the generated namespace mapping table <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;calcProxy calc(SOAP_IO_KEEPALIVE); // keep-alive improves connection performance <br />
&nbsp;&nbsp;&nbsp;<b>double</b>&nbsp;sum = 0.0; <br />
&nbsp;&nbsp;&nbsp;<b>double</b>&nbsp;val[] =  5.0, 3.5, 7.1, 1.2 ; <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(<b>int</b>&nbsp;i = 0; i  &lt;  4; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(calc.add(sum, val[i], sum)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;calc.error; <br />
&nbsp;&nbsp;&nbsp;std::cout  &lt;&lt;  "Sum = "  &lt;&lt;  sum  &lt;&lt;  std::endl; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
}
</td></tr></table><br></i>
In the above, no data is deallocated until the proxy is deleted. To deallocate deserialized data between the calls, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(<b>int</b>&nbsp;i = 0; i  &lt;  4; i++) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(calc.add(sum, val[i], sum)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;calc.error; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;calc.destroy(); <br />
&nbsp;&nbsp;&nbsp;}
</td></tr></table><br></i>
Deallocation is safe here, since the float values were copied and saved in
<i>sum</i>. In other scenarios one must make sure data is copied or removed from
the deallocation chain with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_unlink(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>void</b>&nbsp;*data)
</td></tr></table><br></i>
which is to be invoked on each data item to be preserved, before destroying deallocated data. When the proxy is deleted, also all deserialized data is deleted. To delegate deletion to another runtime context for later removal, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_delegate_deletion(<b>struct</b>&nbsp;soap *soap_from, <b>struct</b>&nbsp;soap *soap_to)
</td></tr></table><br></i>
For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
{ // create proxy <br />
&nbsp;&nbsp;&nbsp;calcProxy calc; <br />
&nbsp;&nbsp;&nbsp;...&nbsp;data generated ... <br />
&nbsp;&nbsp;&nbsp;soap_delegate_deletion(&amp;calc, &amp;soap); <br />
} // proxy deleted <br />
...&nbsp;data used ... <br />
soap_destroy(&amp;soap); <br />
soap_end(&amp;soap); <br />
soap_done(&amp;soap);
</td></tr></table><br></i>
In C (use <i>wsdl2h -c</i>) the example program would be written as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include <tt>"soapH.h"</tt> <br />
#include <tt>"calc.nsmap"</tt> <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>double</b>&nbsp;sum = 0.0; <br />
&nbsp;&nbsp;&nbsp;<b>double</b>&nbsp;val[] =  5.0, 3.5, 7.1, 1.2 ; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;i; <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  4; i++) <br />
&nbsp;&nbsp;&nbsp;soap_init1(&amp;soap, SOAP_IO_KEEPALIVE); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_c__add(&amp;soap, NULL, NULL, sum, val[i], &amp;sum)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap.error; <br />
&nbsp;&nbsp;&nbsp;printf("Sum = %lg<tt>\</tt>n", sum); <br />
&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
}
</td></tr></table><br></i>
The code above is compiled and linked with <i>soapClient.c</i>, <i>soapC.c</i>,
and <i>stdsoap2.c</i> (or use <i>libgsoap.a</i>).

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.2">
7.1.2</a>&nbsp;&nbsp;<font color="#0000FF">XML Namespace Considerations</font></h4><a name="sec:namespace">
</a>

<div class="p"><!----></div>
The declaration of the <i>ns2__add</i> function prototype (discussed in the previous section) uses the namespace prefix
<i>ns2__</i> of the service operation namespace, which is distinguished by a <b>pair of underscores</b> in the function name to
separate the namespace prefix from the service operation name.  The purpose of a namespace prefix is to associate a service
operation name with a service in order to prevent naming conflicts, e.g.&nbsp;to distinguish identical service operation names used
by different services.

<div class="p"><!----></div>
Note that the XML response of the service example uses a <b>namespace prefix</b> that may be different (e.g.&nbsp;<tt>ns</tt>) as long as it bound to the same <b>namespace name</b> <tt>urn:calc</tt> through the <tt>xmlns:ns="urn:calc</tt>
binding.  The use of namespace prefixes and namespace names is also required to enable SOAP applications to validate the content of
SOAP messages.  The namespace name in the service response is verified by the stub routine by using the
information supplied in a <b>namespace mapping table</b> that is required to be part of gSOAP client and service application codes.  The table is accessed
at run time to resolve namespace bindings, both by the generated stub's data structure serializer for encoding the client request
and by the generated stub's data structure deserializer to decode and validate the service response. The namespace mapping table
should <b>not</b> be part of the header file input to the gSOAP <i>soapcpp2</i> tool. Service details including namespace bindings may be provided with gSOAP directives in a header file, see Section&nbsp;<a href="#sec:directives">19.2</a>.

<div class="p"><!----></div>
The namespace mapping table is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{&nbsp;&nbsp;&nbsp;// {"ns-prefix", "ns-name"} <br />
&nbsp;&nbsp;&nbsp;{<font color="#FF0000">"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"</font>}, // MUST be first <br />
&nbsp;&nbsp;&nbsp;{<font color="#0000FF">"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/"</font>}, // MUST be second <br />
&nbsp;&nbsp;&nbsp;{<font color="#FF00FF">"xsi",      "http://www.w3.org/2001/XMLSchema-instance"</font>}, // MUST be third <br />
&nbsp;&nbsp;&nbsp;{<font color="#00FFFF">"xsd",      "http://www.w3.org/2001/XMLSchema"</font>}, // 2001 XML Schema <br />
&nbsp;&nbsp;&nbsp;{<font color="#00FF00">"ns2",      "urn:calc"</font>}, // given by the service description <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} // end of table <br />
};
</td></tr></table><br></i> 
The first four namespace entries in the table consist of the standard namespaces used by the SOAP 1.1 protocol. In fact, the
namespace mapping table is explicitly declared to enable a programmer to specify the SOAP encoding style and to allow the
inclusion of namespace-prefix with namespace-name bindings to comply to the namespace requirements of a specific SOAP service. For
example, the namespace prefix <tt>ns2</tt>, which is bound to <tt>urn:calc</tt> by the namespace mapping table shown
above, is used by the generated stub routine to encode the <i>add</i> request. This is performed automatically by the gSOAP <i>soapcpp2</i>
tool by using the <i>ns2</i> prefix of the <i>ns2__add</i> method name specified in the <i>calc.h</i> header file. In
general, if a function name of a service operation, <i><b>struct</b></i> name, <i><b>class</b></i> name, <i><b>enum</b></i> name, or field name of a
<i><b>struct</b></i> or <i><b>class</b></i> has a pair of underscores, the name has a namespace prefix that must be defined in the namespace
mapping table.

<div class="p"><!----></div>
The namespace mapping table will be output as part of the SOAP Envelope by the stub routine. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
... <br />
&lt;SOAP-ENV:Envelope xmlns:<font color="#FF0000">SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"</font> <br />
&nbsp;&nbsp;&nbsp;xmlns:<font color="#0000FF">SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"</font> <br />
&nbsp;&nbsp;&nbsp;xmlns:<font color="#FF00FF">xsi="http://www.w3.org/2001/XMLSchema-instance"</font> <br />
&nbsp;&nbsp;&nbsp;xmlns:<font color="#00FFFF">xsd="http://www.w3.org/2001/XMLSchema"</font> <br />
&nbsp;&nbsp;&nbsp;xmlns:<font color="#00FF00">ns2="urn:calc"</font> <br />
&nbsp;&nbsp;&nbsp;SOAP-ENV:encodingStyle=<font color="#0000FF">"http://schemas.xmlsoap.org/soap/encoding/"</font>&#62; <br />
...
</td></tr></table><br></tt>
The namespace bindings will be used by a SOAP service to validate the SOAP request.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.3">
7.1.3</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4><a name="sec:example2">
</a>

<div class="p"><!----></div>
The incorporation of namespace prefixes into C++ identifier names is necessary to distinguish service operations that
share the same name but are provided by separate Web services and/or
organizations. It avoids potential name clashes, while sticking to the C
syntax. The C++ proxy classes generated with <i>soapcpp2 -i</i> (or <i>-j</i>) drop the
namespace prefix from the method names

<div class="p"><!----></div>
The namespace prefix convention is also be applied to non-primitive types. For example, <i><b>class</b></i> names are prefixed to avoid name clashes when the same name is used by multiple XML schemas. This ensures that the XML databinding never suffers from conflicting schema content. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;<font color="#FF0000">e__Address</font> // an electronic address from schema 'e' <br />
{ <br />
&nbsp;&nbsp;&nbsp;char *email; <br />
&nbsp;&nbsp;&nbsp;char *url; <br />
}; <br />
<b>class</b>&nbsp;<font color="#0000FF">s__Address</font> // a street address from schema 's' <br />
{ <br />
&nbsp;&nbsp;&nbsp;char *street; <br />
&nbsp;&nbsp;&nbsp;int number; <br />
&nbsp;&nbsp;&nbsp;char *city; <br />
};
</td></tr></table><br></i>
The namespace prefix is separated from the name of a data type by a pair of underscores (<i>__</i>).

<div class="p"><!----></div>
An instance of <i><font color="#FF0000">e__Address</font></i> is encoded by the generated serializer for this type as an Address element with namespace prefix <i><font color="#FF0000">e</font></i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;<font color="#FF0000">e:Address</font> xsi:type="<font color="#FF0000">e:Address</font>"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;email xsi:type="string"&#62;me@home&lt;/email&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;url xsi:type="string"&#62;www.me.com&lt;/url&#62; <br />
&lt;/<font color="#FF0000">e:Address</font>&#62;
</td></tr></table><br></tt>
While an instance of <i><font color="#0000FF">s__Address</font></i> is encoded by the generated serializer for this type as an Address element with namespace prefix <i><font color="#0000FF">s</font></i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;<font color="#0000FF">s:Address</font> xsi:type="<font color="#0000FF">s:Address</font>"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;street xsi:type="string"&#62;Technology Drive&lt;/street&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;number xsi:type="int"&#62;5&lt;/number&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;city xsi:type="string"&#62;Softcity&lt;/city&#62; <br />
&lt;/<font color="#0000FF">s:Address</font>&#62;
</td></tr></table><br></tt>
The namespace mapping table of the client program must have entries for <i><font color="#FF0000">e</font></i> and <i><font color="#0000FF">s</font></i> that refer to the XML Schemas of the data types:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{ ... <br />
&nbsp;&nbsp;&nbsp;{"<font color="#FF0000">e</font>", "http://www.me.com/schemas/electronic-address"}, <br />
&nbsp;&nbsp;&nbsp;{"<font color="#0000FF">s</font>", "http://www.me.com/schemas/street-address"}, <br />
...
</td></tr></table><br></i> 
This table is required to be part of the client application to allow access by the serializers and deserializers of the data types at run time.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.4">
7.1.4</a>&nbsp;&nbsp;<font color="#0000FF">How to Generate C++ Client Proxy Classes</font></h4><a name="sec:proxy">
</a>

<div class="p"><!----></div>
Proxy classes for C++ client applications are automatically generated by the gSOAP <i>soapcpp2</i> tool, as was shown in Section&nbsp;<a href="#sec:example1">7.1.1</a>.

<div class="p"><!----></div>
There is a new and improved code generation capability for proxy classes, which
is activated with the <i>soapcpp2 -i</i> (or <i>j</i>) option. These new proxy classes are
derived from the soap structure, have a cleaner interface and offer more
capabilites.

<div class="p"><!----></div>
With C++, you can also use <i>wsdl2h</i> option <i>-q</i><i>name</i> to generate
the proxy in a C++ namespace <i>name</i>. This is very useful if you want to
create multiple proxies for services by repeated use of <i>wsdl2h</i> and
combine them in one code.  Alternatively, you can run <i>wsdl2h</i> just once on
all service WSDLs and have <i>soapcpp2</i> generate multiple proxies for you.
The latter approach does not use C++ namespaces and may reduce the overall
amount of code.

<div class="p"><!----></div>
To illustrate the generation of a "standard" (old-style) proxy class, the
<i>calc.h</i> header file example of the previous section is augmented with
the appropriate directives to enable the gSOAP <i>soapcpp2</i> tool to generate the proxy
class. Directives are included in the generated header file by the <i>wsdl2h</i> WSDL importer:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Content of file <tt>"calc.h"</tt>: <br />
//gsoap ns2 service name: calc <br />
//gsoap ns2 service port: http://websrv.cs.fsu.edu/&nbsp;engelen/calcserver.cgi <br />
//gsoap ns2 service protocol: SOAP1.1 <br />
//gsoap ns2 service style: rpc <br />
//gsoap ns2 service encoding: encoded <br />
//gsoap ns2 service namespace: urn:calc <br />
<br />
//gsoap ns2 service method-protocol: add SOAP <br />
//gsoap ns2 service method-style: add rpc <br />
//gsoap ns2 service method-encoding: add encoded <br />
//gsoap ns2 service method-action: add "" <br />
<b>int</b>&nbsp;ns2__add(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&amp; result); <br />
<br />
//gsoap ns2 service method-protocol: sub SOAP <br />
//gsoap ns2 service method-style: sub rpc <br />
//gsoap ns2 service method-encoding: sub encoded <br />
//gsoap ns2 service method-action: sub "" <br />
<b>int</b>&nbsp;ns2__sub(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&amp; result); <br />
<br />
//gsoap ns2 service method-protocol: mul SOAP <br />
//gsoap ns2 service method-style: mul rpc <br />
//gsoap ns2 service method-encoding: mul encoded <br />
//gsoap ns2 service method-action: mul "" <br />
<b>int</b>&nbsp;ns2__mul(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&amp; result); <br />
<br />
...
</td></tr></table><br></i>
The first three directives provide the service details, which is used to name the proxy class, the service location port (endpoint), and
the XML namespace. The subsequent groups of three directives per method define the operation's SOAP style (RPC) and encoding (SOAP encoded), and SOAP action string. 
These directives can be provided for each service operation when the SOAPAction is required, such as with SOAP1.1 RPC encoded and when WS-Addressing is used.
In this example, the service protocol is set by default for all operations to use SOAP 1.1 RPC encoding.
For <i>//gsoap</i> directive details, see Section&nbsp;<a href="#sec:directives">19.2</a>.

<div class="p"><!----></div>
The <i>soapcpp2</i> tool takes this header file and generates a proxy <i>soapcalcProxy.h</i> with the
following contents (not using option <i>-i</i>):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
<b>class</b>&nbsp;calc <br />
{ <b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap *soap; <br />
&nbsp;&nbsp;&nbsp;<b>const</b>&nbsp;<b>char</b>&nbsp;*endpoint; <br />
&nbsp;&nbsp;&nbsp;calc() { ... }; <br />
&nbsp;&nbsp;&nbsp;~calc() { ... }; <br />
&nbsp;&nbsp;&nbsp;<b>virtual</b>&nbsp;<b>int</b>&nbsp;ns2__add(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&amp; result) { <b>return</b>&nbsp;soap ? soap_call_ns2__add(soap, endpoint, NULL, a, b, result) : SOAP_EOM; }; <br />
&nbsp;&nbsp;&nbsp;<b>virtual</b>&nbsp;<b>int</b>&nbsp;ns2__sub(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&amp; result) { <b>return</b>&nbsp;soap ? soap_call_ns2__sub(soap, endpoint, NULL, a, b, result) : SOAP_EOM; }; <br />
&nbsp;&nbsp;&nbsp;<b>virtual</b>&nbsp;<b>int</b>&nbsp;ns2__mul(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&amp; result) { <b>return</b>&nbsp;soap ? soap_call_ns2__mul(soap, endpoint, NULL, a, b, result) : SOAP_EOM; }; <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
The gSOAP context and endpoint are declared public to enable access.

<div class="p"><!----></div>
This generated proxy class can be included into a client application together with the generated namespace table as shown in this example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapcalcProxy.h"	// get proxy <br />
#include "calc.nsmap"		// get namespace bindings <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;calc s; <br />
&nbsp;&nbsp;&nbsp;<b>double</b>&nbsp;r; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(s.ns2__add(1.0, 2.0, r) == SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;std::cout  &lt;&lt;  r  &lt;&lt;  std::endl; <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(s.soap, stderr); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
}
</td></tr></table><br></i>
The constructor allocates and initializes a gSOAP context for the instance.

<div class="p"><!----></div>
You can use <i>soapcpp2</i> option <i>-n</i> together with <i>-p</i> to create
a local namespaces table to avoid link conflicts when you need multiple
namespace tables or need to combine multiple clients, see also
Sections&nbsp;<a href="#sec:options">9.1</a> and&nbsp;<a href="#sec:dylibs">19.36</a>, and you can use a C++ code
<i><b>namespace</b></i> to create a namespace qualified proxy class, see
Section&nbsp;<a href="#sec:codenamespace">19.35</a>.

<div class="p"><!----></div>
The <i>soapcpp2 -i</i> option to generate proxy classes
derived from the base soap structure. In addition, these classes offer more
functionality as illustrated in Section&nbsp;<a href="#sec:example1">7.1.1</a>.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.5">
7.1.5</a>&nbsp;&nbsp;<font color="#0000FF">XSD Type Encoding Considerations</font></h4><a name="sec:encoding">
</a>

<div class="p"><!----></div>
Many SOAP services require the explicit use of XML Schema types in the SOAP payload. The default encoding, which is also adopted
by the gSOAP <i>soapcpp2</i> tool, assumes SOAP RPC encoding which only requires the use of types to handle polymorphic cases.
Nevertheless, the use of XSD typed messages is advised to improve interoperability.
XSD types are introduced with <i><b>typedef</b></i> definitions in
the header file input to the gSOAP <i>soapcpp2</i> tool. The type name defined by a <i><b>typedef</b></i> definition corresponds to an XML Schema
type (XSD type). For example, the following <i><b>typedef</b></i> declarations
define various built-in XSD types implemented as primitive C/C++ types:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of header file: <br />
... <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string; // encode xsd__string value as the <span class="roman"><tt>xsd:string</tt></span> schema type <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__anyURI; // encode xsd__anyURI value as the <span class="roman"><tt>xsd:anyURI</tt></span> schema type <br />
<b>typedef</b>&nbsp;<b>float</b>&nbsp;xsd__float; // encode xsd__float value as the <span class="roman"><tt>xsd:float</tt></span> schema type <br />
<b>typedef</b>&nbsp;<b>long</b>&nbsp;xsd__int; // encode xsd__int value as the <span class="roman"><tt>xsd:int</tt></span> schema type <br />
<b>typedef</b>&nbsp;<b>bool</b>&nbsp;xsd__boolean; // encode xsd__boolean value as the <span class="roman"><tt>xsd:boolean</tt></span> schema type <br />
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>long</b>&nbsp;<b>long</b>&nbsp;xsd__positiveInteger; // encode xsd__positiveInteger value as the <span class="roman"><tt>xsd:positiveInteger</tt></span>  schema type<br />
...
</td></tr></table><br></i>
This easy-to-use mechanism informs the gSOAP <i>soapcpp2</i> tool to generate serializers and deserializers that explicitly encode and decode the
primitive C++ types as built-in primitive XSD types when the <i>typedef</i>ed type is used in the parameter signature of a
service operation (or when used nested within structs, classes, and arrays).  At the same time, the use of <i><b>typedef</b></i> 
does not force any recoding of a C++ client or Web service application as the internal C++ types used by the application
are not required to be changed (but still have to be primitive C++ types, see Section&nbsp;<a href="#sec:primclass">11.3.2</a> for alternative class
implementations of primitive XSD types which allows for the marshalling of polymorphic primitive types).

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.6">
7.1.6</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4><a name="sec:example3">
</a>

<div class="p"><!----></div>
Reconsider the calculator example, now rewritten with explicit XSD types to illustrate the effect:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "calc.h": <br />
<b>typedef</b>&nbsp;<b>double</b>&nbsp;<font color="#FF0000">xsd__double</font>; <br />
<b>int</b>&nbsp;<font color="#00FF00">ns2__add</font>(<font color="#FF0000">xsd__string</font> <font color="#FF00FF">a</font>, <font color="#FF0000">xsd__double</font> <font color="#0000FF">b</font>, <font color="#FF0000">xsd__double</font> &amp;<font color="#00FFFF">Result</font>);
</td></tr></table><br></i>
When processed by the gSOAP <i>soapcpp2</i> tool it generates source code for the function
<i>soap_call_ns2__add</i>, which is identical to the C-style SOAP call:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;soap_call_ns2__add(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*URL, <b>char</b>&nbsp;*action, <b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&amp; result);
</td></tr></table><br></i>
The client application does not need to be rewritten and can still call the proxy using the "old" C-style function signatures. In contrast to
the previous implementation of the stub however, the encoding and decoding of the data types by the stub has been changed to
explicitly use the XSD types in the message payload.

<div class="p"><!----></div>
For example, when the client application calls the proxy, the proxy produces a SOAP request with an <tt>xsd:double</tt> (the <tt>xsi:type</tt> is shown when the <i>soapcpp2 -t</i> option is used):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
... <br />
&lt;SOAP-ENV:Body&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;<font color="#00FF00">ns2:add</font>&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;<font color="#FF00FF">a</font> xsi:type="<font color="#FF0000">xsd:string</font>"&#62;1.0&lt;/<font color="#FF00FF">a</font>&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;<font color="#0000FF">b</font> xsi:type="<font color="#FF0000">xsd:string</font>"&#62;2.0&lt;/<font color="#0000FF">b</font>&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/<font color="#00FF00">ns2:add</font>&#62; <br />
&lt;/SOAP-ENV:Body&#62; <br />
...
</td></tr></table><br></tt>
The service response is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
... <br />
&lt;soap:Body&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;<font color="#00FF00">n:add</font>Response xmlns:n="urn:calc"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;<font color="#00FFFF">result</font> xsi:type="<font color="#FF0000">xsd:double</font>"&#62;3.0&lt;/<font color="#00FFFF">result</font>&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/<font color="#00FF00">n:add</font>Response&#62; <br />
&lt;/soap:Body&#62; <br />
...
</td></tr></table><br></tt>
The validation of this service response by the stub routine takes place by matching the namespace names (URIs) that are bound to the
<tt>xsd</tt> namespace prefix. The stub also expects the <tt>addResponse</tt> element to be associated with URI
<tt>urn:calc</tt> through the binding of the namespace prefix <tt>ns2</tt> in the namespace mapping table. The
service response uses namespace prefix <tt>n</tt> for the <tt>addResponse</tt> element. This namespace prefix is bound to the same
URI <tt>urn:calc</tt> and therefore the service response is valid.  When the XML is not well formed or does not pass validation, the response is
rejected and a SOAP fault is generated. The validation level can be increased with the <i>SOAP_XML_STRICT</i> flag, but this is not advised for SOAP RPC encoded messaging.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.7">
7.1.7</a>&nbsp;&nbsp;<font color="#0000FF">How to Change the Response Element Name</font></h4><a name="sec:response">
</a>

<div class="p"><!----></div>
There is no standardized convention for the response element name in a SOAP RPC encoded response message, although it is recommended that the response
element name is the method name ending with "<tt>Response</tt>". For example, the response element of <tt>add</tt> is
<tt>addResponse</tt>.

<div class="p"><!----></div>
The response element name can be specified explicitly using a <i><b>struct</b></i> or
<i><b>class</b></i> declaration in the header file. This name must be qualified by a
namespace prefix, just as the operation name should use a namespace prefix. The
<i><b>struct</b></i> or <i><b>class</b></i> name represents the SOAP response element name
used by the service. Consequently, the output
parameter of the service operation must be declared as a field of the <i><b>struct</b></i> or <i><b>class</b></i>.  The use of a <i><b>struct</b></i> or a
<i><b>class</b></i> for the service response is fully SOAP 1.1 compliant. In fact, the absence of a <i><b>struct</b></i> or <i><b>class</b></i>
indicates to the <i>soapcpp2</i> tool to automatically generate a <i>struct</i> for the response which is internally used by a stub.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.8">
7.1.8</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4><a name="sec:example4">
</a>

<div class="p"><!----></div>
Reconsider the calculator service operation specification which can be rewritten with an explicit declaration of a SOAP response
element as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of "calc.h": <br />
<b>typedef</b>&nbsp;<b>double</b>&nbsp;<font color="#FF0000">xsd__double</font>; <br />
<b>struct</b>&nbsp;<font color="#FFFF00">ns2__addResponse</font> {<font color="#FF0000">xsd__double</font> <font color="#00FFFF">result</font>;}; <br />
<b>int</b>&nbsp;<font color="#00FF00">ns2__add</font>(<font color="#FF0000">xsd__string</font> <font color="#FF00FF">a</font>, <font color="#FF0000">xsd__double</font> <font color="#0000FF">b</font>, <b>struct</b>&nbsp;<font color="#FFFF00">ns2__addResponse</font> &amp;r);
</td></tr></table><br></i>
The SOAP request and response messages are the same as before:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
... <br />
&lt;SOAP-ENV:Body&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;<font color="#00FF00">ns2:add</font>&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;<font color="#FF00FF">a</font> xsi:type="<font color="#FF0000">xsd:string</font>"&#62;1.0&lt;/<font color="#FF00FF">a</font>&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;<font color="#0000FF">b</font> xsi:type="<font color="#FF0000">xsd:string</font>"&#62;2.0&lt;/<font color="#0000FF">b</font>&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/<font color="#00FF00">ns2:add</font>&#62; <br />
&lt;/SOAP-ENV:Body&#62; <br />
...
</td></tr></table><br></tt>
The difference is that the service response is required to match the specified <i>addResponse</i> name and its namespace URI:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
... <br />
&lt;soap:Body&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;<font color="#FFFF00">n:addResponse</font> xmlns:n='urn:calc'&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;<font color="#00FFFF">result</font> xsi:type="<font color="#FF0000">xsd:double</font>"&#62;3.0&lt;/<font color="#00FFFF">result</font>&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/<font color="#FFFF00">n:addResponse</font>&#62; <br />
&lt;/soap:Body&#62; <br />
...
</td></tr></table><br></tt>
This use of a <i><b>struct</b></i> or <i><b>class</b></i> enables the adaptation of the default SOAP response element name and/or namespace URI when required.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.9">
7.1.9</a>&nbsp;&nbsp;<font color="#0000FF">How to Specify Multiple Output Parameters</font></h4><a name="sec:multiple">
</a>

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> tool compiler uses the convention that the 
<b>last parameter</b> of the function prototype declaration of a service operation in a header file
is also the <b>only single output parameter</b> of the method.
All other parameters are considered input parameters of the service operation. To specify a service operation
with <b>multiple output parameters</b>, a <i><b>struct</b></i> or <i><b>class</b></i> must be declared for the service operation response, see
also&nbsp;<a href="#sec:response">7.1.7</a>.  The name of the <i><b>struct</b></i> or <i><b>class</b></i> must have a namespace prefix, just as the service method name. The fields of the <i><b>struct</b></i> or <i><b>class</b></i> are the output parameters of the service operation.
Both the order of the input parameters in the function prototype and the order of the output parameters (the fields in the
<i><b>struct</b></i> or <i><b>class</b></i>) is not significant. However, the SOAP 1.1 specification states that input and output parameters may be
treated as having anonymous parameter names which requires a particular ordering, see Section&nbsp;<a href="#sec:anonymous">7.1.13</a>.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.10">
7.1.10</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4><a name="sec:example5">
</a>

<div class="p"><!----></div>
As an example, consider a hypothetical service operation <i>getNames</i> with a single input parameter <i><font color="#FF00FF">SSN</font></i> 
and two output parameters <i><font color="#FF0000">first</font></i> and <i><font color="#0000FF">last</font></i>. This can be specified as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "getNames.h": <br />
<b>int</b>&nbsp;<font color="#00FF00">ns3__getNames</font>(<b>char</b>&nbsp;*<font color="#FF00FF">SSN</font>, <b>struct</b>&nbsp;<font color="#FFFF00">ns3__getNamesResponse</font> {<b>char</b>&nbsp;*<font color="#FF0000">first</font>; <b>char</b>&nbsp;*<font color="#0000FF">last</font>;} &amp;r);
</td></tr></table><br></i>
The gSOAP <i>soapcpp2</i> tool takes this header file as input and generates source code for the function <i>soap_call_ns3__getNames</i>. When invoked by a client application, the proxy produces the SOAP request:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
... <br />
&lt;SOAP-ENV:Envelope ... xmlns:ns3="urn:names" ...&#62; <br />
... <br />
&lt;<font color="#00FF00">ns3:getNames</font>&#62; <br />
&lt;<font color="#FF00FF">SSN</font>&#62;999 99 9999&lt;/<font color="#FF00FF">SSN</font>&#62; <br />
&lt;/<font color="#00FF00">ns3:getNames</font>&#62; <br />
...
</td></tr></table><br></tt>
The response by a SOAP service could be:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
... <br />
&lt;<font color="#FFFF00">m:getNamesResponse</font> xmlns:m="urn:names"&#62; <br />
&lt;<font color="#FF0000">first</font>&#62;John&lt;/<font color="#FF0000">first</font>&#62; <br />
&lt;<font color="#0000FF">last</font>&#62;Doe&lt;/<font color="#0000FF">last</font>&#62; <br />
&lt;/<font color="#FFFF00">m:getNamesResponse</font>&#62; <br />
...
</td></tr></table><br></tt>
where <tt><font color="#FF0000">first</font></tt> and <tt><font color="#0000FF">last</font></tt> are the output parameters of the <i>getNames</i> service operation of the service.

<div class="p"><!----></div>
As another example, consider a service operation <i>copy</i> with an input parameter and an output parameter with identical
parameter names (this is not prohibited by the SOAP 1.1 protocol). This can be specified as well using a response <i><b>struct</b></i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Content of file "copy.h": <br />
<b>int</b>&nbsp;<font color="#00FF00">X_rox__copy_name</font>(<b>char</b>&nbsp;*<font color="#FF00FF">name</font>, <b>struct</b>&nbsp;<font color="#FFFF00">X_rox__copy_nameResponse</font> {<b>char</b>&nbsp;*<font color="#FF0000">name</font>;} &amp;r);
</td></tr></table><br></i>
The use of a <i><b>struct</b></i> or <i><b>class</b></i> for the service operation response enables the declaration of service operations that have
parameters that are passed both as input and output parameters.

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> compiler takes the <i>copy.h</i> header file as input and generates the <i>soap_call_X_rox__copy_name</i> proxy. When invoked by a client application, the proxy produces the SOAP request:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
... <br />
&lt;SOAP-ENV:Envelope ... xmlns:X-rox="urn:copy" ...&#62; <br />
... <br />
&lt;<font color="#00FF00">X-rox:copy-name</font>&#62; <br />
&lt;<font color="#FF00FF">name</font>&#62;SOAP&lt;/<font color="#FF00FF">name</font>&#62; <br />
&lt;/<font color="#00FF00">X-rox:copy-name</font>&#62; <br />
...
</td></tr></table><br></tt>
The response by a SOAP copy service could be something like:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
... <br />
&lt;<font color="#FFFF00">m:copy-nameResponse</font> xmlns:m="urn:copy"&#62; <br />
&lt;<font color="#FF0000">name</font>&#62;SOAP&lt;/<font color="#FF0000">name</font>&#62; <br />
&lt;/<font color="#FFFF00">m:copy-nameResponse</font>&#62; <br />
...
</td></tr></table><br></tt>
The name will be parsed and decoded by the proxy and returned in the <i>name</i> field of the <i><b>struct</b>&nbsp;X_rox__copy_nameResponse &amp;r</i> parameter.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.11">
7.1.11</a>&nbsp;&nbsp;<font color="#0000FF">How to Specify Output Parameters With struct/class Compound Data Types</font></h4><a name="sec:compound">
</a>

<div class="p"><!----></div>
If the single output parameter of a service operation is a complex data type such as a <i><b>struct</b></i> or <i><b>class</b></i> it is necessary to
specify the response element of the service operation as a <i><b>struct</b></i> or <i><b>class</b></i> <b>at all times</b>.
Otherwise, the output parameter will
be considered the response element (!), because of the response element specification convention used by gSOAP,
as discussed in&nbsp;<a href="#sec:response">7.1.7</a>.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.12">
7.1.12</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4><a name="sec:example6">
</a>

<div class="p"><!----></div>
This is best illustrated with an example. The Flighttracker service by ObjectSpace provides real time flight information for
flights in the air. It requires an airline code and flight number as parameters.
The service operation name is <i>getFlightInfo</i> and
the method has two string parameters: the airline code and flight number, both of which must be encoded as <tt>xsd:string</tt> types.
The method returns a <i>getFlightResponse</i> response element with a <i>return</i> output parameter that is of complex type
<i>FlightInfo</i>. The type <i>FlightInfo</i> is represented by a <i><b>class</b></i> in the header file, whose field names correspond to
the <i>FlightInfo</i> accessors:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "flight.h": <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string; <br />
<b>class</b>&nbsp;ns2__FlightInfo <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;xsd__string airline; <br />
&nbsp;&nbsp;&nbsp;xsd__string flightNumber; <br />
&nbsp;&nbsp;&nbsp;xsd__string altitude; <br />
&nbsp;&nbsp;&nbsp;xsd__string currentLocation; <br />
&nbsp;&nbsp;&nbsp;xsd__string equipment; <br />
&nbsp;&nbsp;&nbsp;xsd__string speed; <br />
}; <br />
<b>struct</b>&nbsp;ns1__getFlightInfoResponse {ns2__FlightInfo return_;}; <br />
<b>int</b>&nbsp;ns1__getFlightInfo(xsd__string param1, xsd__string param2, <b>struct</b>&nbsp;ns1__getFlightInfoResponse &amp;r);
</td></tr></table><br></i>
The response element <i>ns1__getFlightInfoResponse</i> is explicitly declared and it has one field: <i>return_</i> of type
<i>ns2__FlightInfo</i>.  Note that <i>return_</i> has a trailing underscore to avoid a name clash with the <i><b>return</b></i> keyword,
see Section&nbsp;<a href="#sec:idtrans">10.3</a> for details on the translation of C++ identifiers to XML element names.

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> compiler generates the <i>soap_call_ns1__getFlightInfo</i> proxy. Here is an example fragment of a client application that uses this proxy to request flight information:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
... <br />
soap_init(&amp;soap); <br />
... <br />
soap_call_ns1__getFlightInfo(&amp;soap, <tt>"testvger.objectspace.com/soap/servlet/rpcrouter"</tt>, <br />
&nbsp;&nbsp;&nbsp;<tt>"urn:galdemo:flighttracker"</tt>, <tt>"UAL"</tt>, <tt>"184"</tt>, r); <br />
... <br />
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{ <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC","http://schemas.xmlsoap.org/soap/encoding/"}, <br />
&nbsp;&nbsp;&nbsp;{"xsi", "http://www.w3.org/2001/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd", "http://www.w3.org/2001/XMLSchema"}, <br />
&nbsp;&nbsp;&nbsp;{"ns1", "urn:galdemo:flighttracker"}, <br />
&nbsp;&nbsp;&nbsp;{"ns2", "http://galdemo.flighttracker.com"}, <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} <br />
};
</td></tr></table><br></i>
When invoked by a client application, the proxy produces the SOAP request:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
POST /soap/servlet/rpcrouter HTTP/1.1 <br />
Host: testvger.objectspace.com <br />
Content-Type: text/xml <br />
Content-Length: 634 <br />
SOAPAction: "urn:galdemo:flighttracker" <br />
<br />
&lt;?xml version="1.0" encoding="UTF-8"?&#62; <br />
&lt;SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsd="http://www.w3.org/2001/XMLSchema" <br />
&nbsp;&nbsp;&nbsp;xmlns:ns1="urn:galdemo:flighttracker" <br />
&nbsp;&nbsp;&nbsp;xmlns:ns2="http://galdemo.flighttracker.com" <br />
&nbsp;&nbsp;&nbsp;SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&#62; <br />
&lt;SOAP-ENV:Body&#62; <br />
&lt;ns1:getFlightInfo xsi:type="ns1:getFlightInfo"&#62; <br />
&lt;param1 xsi:type="xsd:string"&#62;UAL&lt;/param1&#62; <br />
&lt;param2 xsi:type="xsd:string"&#62;184&lt;/param2&#62; <br />
&lt;/ns1:getFlightInfo&#62; <br />
&lt;/SOAP-ENV:Body&#62; <br />
&lt;/SOAP-ENV:Envelope&#62;
</td></tr></table><br></tt>
The Flighttracker service responds with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
HTTP/1.1 200 ok <br />
Date: Thu, 30 Aug 2001 00:34:17 GMT <br />
Server: IBM_HTTP_Server/1.3.12.3 Apache/1.3.12 (Win32) <br />
Set-Cookie: sesessionid=2GFVTOGC30D0LGRGU2L4HFA;Path=/ <br />
Cache-Control: no-cache="set-cookie,set-cookie2" <br />
Expires: Thu, 01 Dec 1994 16:00:00 GMT <br />
Content-Length: 861 <br />
Content-Type: text/xml; charset=utf-8 <br />
Content-Language: en <br />
<br />
&lt;?xml version="1.0" encoding="UTF-8"?&#62; <br />
&lt;SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsd="http://www.w3.org/2001/XMLSchema"&#62; <br />
&lt;SOAP-ENV:Body&#62; <br />
&lt;ns1:getFlightInfoResponse xmlns:ns1="urn:galdemo:flighttracker" <br />
&nbsp;&nbsp;&nbsp;SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&#62; <br />
&lt;return xmlns:ns2="http://galdemo.flighttracker.com" xsi:type="ns2:FlightInfo"&#62; <br />
&lt;equipment xsi:type="xsd:string"&#62;A320&lt;/equipment&#62; <br />
&lt;airline xsi:type="xsd:string"&#62;UAL&lt;/airline&#62; <br />
&lt;currentLocation xsi:type="xsd:string"&#62;188 mi W of Lincoln, NE&lt;/currentLocation&#62; <br />
&lt;altitude xsi:type="xsd:string"&#62;37000&lt;/altitude&#62; <br />
&lt;speed xsi:type="xsd:string"&#62;497&lt;/speed&#62; <br />
&lt;flightNumber xsi:type="xsd:string"&#62;184&lt;/flightNumber&#62; <br />
&lt;/return&#62; <br />
&lt;/ns1:getFlightInfoResponse&#62; <br />
&lt;/SOAP-ENV:Body&#62; <br />
&lt;/SOAP-ENV:Envelope&#62;
</td></tr></table><br></tt>
The proxy returns the service response in variable <i>r</i> of type <i><b>struct</b>&nbsp;ns1__getFlightInfoResponse</i> and this information can be displayed by the client application with the following code fragment:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
cout  &lt;&lt;  r.return_.equipment  &lt;&lt;  " flight "  &lt;&lt;  r.return_.airline  &lt;&lt;  r.return_.flightNumber <br />
&nbsp;&nbsp;&nbsp; &lt;&lt;  " traveling "  &lt;&lt;  r.return_.speed  &lt;&lt;  " mph "  &lt;&lt;  " at "  &lt;&lt;  r.return_.altitude <br />
&nbsp;&nbsp;&nbsp; &lt;&lt;  " ft, is located "  &lt;&lt;  r.return_.currentLocation  &lt;&lt;  endl;
</td></tr></table><br></i>
This code displays the service response as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<tt>A320 flight UAL184 traveling 497 mph at 37000 ft, is located 188 mi W of Lincoln, NE</tt>
</td></tr></table><br></span>
Note: the flight tracker service is no longer available since 9/11/2001. It is kept in the documentation as an example to illustrate the use of structs/classes and response types.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.13">
7.1.13</a>&nbsp;&nbsp;<font color="#0000FF">How to Specify Anonymous Parameter Names</font></h4><a name="sec:anonymous">
</a>

<div class="p"><!----></div>
The SOAP RPC encoding protocol allows parameter names to be anonymous.  That is, the name(s) of the output
parameters of a service operation are not strictly required to match a client's view of the parameters names.  Also, the
input parameter names of a service operation are not strictly required to match a service's view of the parameter names. 
The gSOAP <i>soapcpp2</i> compiler can generate stub and skeleton
routines that support anonymous parameters.  Parameter names are implicitly
anonymous by omitting the parameter names in the function prototype of the
service operation. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of "calc.h": <br />
<b>typedef</b>&nbsp;<b>double</b>&nbsp;xsd__double; <br />
<b>int</b>&nbsp;<font color="#00FF00">ns2__add</font>(<font color="#FF0000">xsd__string</font>, <font color="#FF0000">xsd__double</font>, <font color="#FF0000">xsd__double</font> &amp;);
</td></tr></table><br></i>
To make parameter names explicitly anonymous on the receiving side (client or service),
the parameter names should start with an underscore (<i>_</i>) in the function prototype in the header file.

<div class="p"><!----></div>
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of "calc.h": <br />
<b>typedef</b>&nbsp;<b>double</b>&nbsp;xsd__double; <br />
<b>int</b>&nbsp;<font color="#00FF00">ns2__add</font>(<font color="#FF0000">xsd__string</font> _a, <font color="#FF0000">xsd__double</font> _b, <font color="#FF0000">xsd__double</font> &amp; _return);
</td></tr></table><br></i>
In this example, the <i>_a</i>, <i>_b</i>, and <i>_return</i> are anonymous parameters.
As a consequence, the service response to a request made by a client created with gSOAP using this header file specification
may include any name for the output parameter in the SOAP payload.
The input parameters may also be anonymous. This affects the implementation of Web services in gSOAP
and the matching of parameter names by the service.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: when anonymous parameter names are used, the order of the parameters in the function prototype of a service operation is
significant.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.14">
7.1.14</a>&nbsp;&nbsp;<font color="#0000FF">How to Specify a Method with No Input Parameters</font></h4>

<div class="p"><!----></div>
To specify a service operation that has no input parameters, just provide a function prototype with one parameter which is the output
parameter (some C/C++ compilers will not compile and complain about an empty
<i><b>struct</b></i>: use compile flag <i>-DWITH_NOEMPTYSTRUCT</i> to compile the generated code for these cases). This <i><b>struct</b></i> is generated by gSOAP to contain the SOAP request message.  To fix this, provide one input
parameter of type <i><b>void</b>*</i> (gSOAP can not serialize <i>void*</i> data).  For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns3__SOAPService <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;ID; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*owner; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*description; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*homepageURL; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*endpoint; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*SOAPAction; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*methodNamespaceURI; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*serviceStatus; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*methodName; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*dateCreated; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*downloadURL; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*wsdlURL; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*instructions; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*contactEmail; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*serverImplementation; <br />
}; <br />
<b>struct</b>&nbsp;ArrayOfSOAPService {<b>struct</b>&nbsp;ns3__SOAPService *__ptr; <b>int</b>&nbsp;__size;}; <br />
<b>int</b>&nbsp;ns__getAllSOAPServices(<b>void</b>&nbsp;*_, <b>struct</b>&nbsp;ArrayOfSOAPService &amp;_return);
</td></tr></table><br></i>
The <i>ns__getAllSOAPServices</i> method has one <i><b>void</b>*</i> input parameter which is ignored by the serializer to produce the
request message.

<div class="p"><!----></div>
Most C/C++ compilers allow empty <i><b>struct</b></i>s and therefore the <i><b>void</b>*</i> parameter is not required.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.1.15">
7.1.15</a>&nbsp;&nbsp;<font color="#0000FF">How to Specify a Method with No Output Parameters</font></h4>

<div class="p"><!----></div>
To specify a service operation that has no output parameters, just define a function prototype with a response struct that is
empty. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;ns__event { off, on, stand_by }; <br />
<b>int</b>&nbsp;ns__signal(<b>enum</b>&nbsp;ns__event in, <b>struct</b>&nbsp;ns__signalResponse { } *out);
</td></tr></table><br></i>
Since the response struct is empty, no output parameters are specified.

<div class="p"><!----></div>
Some SOAP resources refer to SOAP RPC with empty responses as <b>one way</b> SOAP messaging. However, we refer to one-way massaging
by asynchronous explicit send and receive operations as described in Section&nbsp;<a href="#sec:oneway1">7.3</a>.  The latter view of one-way SOAP messaging is also in line with Basic Profile 1.0.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc7.2">
7.2</a>&nbsp;&nbsp;<font color="#0000FF">How to Build SOAP/XML Web Services</font></h3>

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> compiler generates <b>skeleton</b> routines in C++ source form for each of the service operations specified
as function prototypes in the header file processed by the gSOAP <i>soapcpp2</i> compiler.  The skeleton routines can be readily used to implement
the service operations in a new SOAP Web service. The compound data types used by the input and output parameters of service operations
must be declared in the header file, such as structs, classes, arrays, and pointer-based data structures (graphs) that are
used as the data types of the parameters of a service operation. The gSOAP <i>soapcpp2</i> compiler automatically generates serializers and
deserializers for the data types to enable the generated skeleton routines to encode and decode the contents of the parameters of
the service operations.  The gSOAP <i>soapcpp2</i> compiler also generates a service operation request dispatcher routine that will serve requests by
calling the appropriate skeleton when the SOAP service application is installed as a CGI application on a Web server.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.1">
7.2.1</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4><a name="sec:example7">
</a>

<div class="p"><!----></div>
The following example specifies three service operations to be implemented by a new SOAP Web service:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "calc.h": <br />
<b>typedef</b>&nbsp;<b>double</b>&nbsp;xsd__double; <br />
<b>int</b>&nbsp;ns__add(xsd__double a, xsd__double b, xsd__double &amp;result); <br />
<b>int</b>&nbsp;ns__sub(xsd__double a, xsd__double b, xsd__double &amp;result); <br />
<b>int</b>&nbsp;ns__sqrt(xsd__double a, xsd__double &amp;result); <br />
</td></tr></table><br></i>
The <i>add</i> and <i>sub</i> methods are intended to add and subtract two double floating point numbers stored in input parameters
<i>a</i> and <i>b</i> and should return the result of the operation in the <i>result</i> output parameter. The <i>sqrt</i> method is
intended to take the square root of input parameter <i>a</i> and to return the result in the output parameter <i>result</i>.
The <i>xsd__double</i> type is recognized by the gSOAP <i>soapcpp2</i> compiler as the <tt>xsd:double</tt> XSD Schema data type.
The use of <i><b>typedef</b></i> is a convenient way to associate primitive C types with primitive XML Schema data types.

<div class="p"><!----></div>
To generate the skeleton routines, the gSOAP <i>soapcpp2</i> compiler is invoked from the command line with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 calc.h</i>
</td></tr></table><br></span>
The compiler generates the skeleton routines for the <i>add</i>, <i>sub</i>, and <i>sqrt</i> service operations specified in the
<i>calc.h</i> header file. The skeleton routines are respectively, <i>soap_serve_ns__add</i>, <i>soap_serve_ns__sub</i>, and
<i>soap_serve_ns__sqrt</i> and saved in the file <i>soapServer.cpp</i>. The generated file <i>soapC.cpp</i> contains serializers
and deserializers for the skeleton. The compiler also generates a service dispatcher: the <i>soap_serve</i> function handles
client requests on the standard input stream and dispatches the service operation requests to the appropriate skeletons to serve the
requests. The skeleton in turn calls the service operation implementation function. The function prototype of the service operation
implementation function is specified in the header file that is input to the gSOAP <i>soapcpp2</i> compiler.

<div class="p"><!----></div>
Here is an example Calculator service application that uses the generated <i>soap_serve</i> routine to handle client requests:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "calc.cpp": <br />
#include "soapH.h" <br />
#include  &lt; math.h &gt;  // for sqrt() <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_serve(soap_new()); // use the service operation request dispatcher <br />
} <br />
// Implementation of the "add" service operation: <br />
<b>int</b>&nbsp;ns__add(<b>struct</b>&nbsp;soap *soap, <b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result) <br />
{ <br />
&nbsp;&nbsp;&nbsp;result = a + b; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
// Implementation of the "sub" service operation: <br />
<b>int</b>&nbsp;ns__sub(<b>struct</b>&nbsp;soap *soap, <b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result) <br />
{ <br />
&nbsp;&nbsp;&nbsp;result = a - b; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
// Implementation of the "sqrt" service operation: <br />
<b>int</b>&nbsp;ns__sqrt(<b>struct</b>&nbsp;soap *soap, <b>double</b>&nbsp;a, <b>double</b>&nbsp;&amp;result) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(a  &gt; = 0) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;result = sqrt(a); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_receiver_fault(soap, "Square root of negative number", "I can only take the square root of a non-negative number"); <br />
} <br />
// As always, a namespace mapping table is needed: <br />
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{&nbsp;&nbsp;&nbsp;// {"ns-prefix", "ns-name"} <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/"}, <br />
&nbsp;&nbsp;&nbsp;{"xsi",      "http://www.w3.org/2001/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd",      "http://www.w3.org/2001/XMLSchema"}, <br />
&nbsp;&nbsp;&nbsp;{"ns",       "urn:simple-calc"}, // bind "ns" namespace prefix <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} <br />
};
</td></tr></table><br></i>
Note that the service operations have an extra input parameter which is a pointer to the gSOAP runtime context.
The implementation of the service operations MUST return a SOAP error code. The code <i>SOAP_OK</i> denotes success, while
<i>SOAP_FAULT</i> denotes an exception with details that can be defined by the user. The exception description can be assigned to
the <i>soap</i><tt>-&gt;</tt><i>fault</i><tt>-&gt;</tt><i>faultstring</i> string and details can be assigned to the
<i>soap</i><tt>-&gt;</tt><i>fault</i><tt>-&gt;</tt><i>detail</i> string. This is SOAP 1.1 specific. SOAP 1.2 requires
the <i>soap</i><tt>-&gt;</tt><i>fault</i><tt>-&gt;</tt><i>SOAP_ENV__Reason</i> and the
<i>soap</i><tt>-&gt;</tt><i>fault</i><tt>-&gt;</tt><i>SOAP_ENV__Detail</i> strings to be assigned.
Better is to use the
<i>soap_receiver_fault</i> function that allocates a fault struct and sets the SOAP Fault string and details
regardless of the SOAP 1.1 or SOAP 1.2 version used. The <i>soap_receiver_fault</i> function returns
<i>SOAP_FAULT</i>, i.e.&nbsp;an application-specific fault. The fault exception will be passed on to the client of this service.

<div class="p"><!----></div>
This service application can be readily installed as a CGI application. The service description would be:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left">Endpoint URL: </td><td align="left">the URL of the CGI application </td></tr>
<tr><td align="left">SOAP action: </td><td align="left">"" (2 quotes) </td></tr>
<tr><td align="left">Remote method namespace: </td><td align="left"><tt>urn:simple-calc</tt> </td></tr>
<tr><td align="left">Remote method name: </td><td align="left"><tt>add</tt> </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;Input parameters: </td><td align="left"><tt>a</tt> of type <tt>xsd:double</tt> and <tt>b</tt> of type <tt>xsd:double</tt> </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;Output parameter: </td><td align="left"><tt>result</tt> of type <tt>xsd:double</tt> </td></tr>
<tr><td align="left">Remote method name: </td><td align="left"><tt>sub</tt> </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;Input parameters: </td><td align="left"><tt>a</tt> of type <tt>xsd:double</tt> and <tt>b</tt> of type <tt>xsd:double</tt> </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;Output parameter: </td><td align="left"><tt>result</tt> of type <tt>xsd:double</tt> </td></tr>
<tr><td align="left">Remote method name: </td><td align="left"><tt>sqrt</tt> </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;Input parameter: </td><td align="left"><tt>a</tt> of type <tt>xsd:double</tt> </td></tr>
<tr><td align="left">&nbsp;&nbsp;&nbsp;Output parameter: </td><td align="left"><tt>result</tt> of type <tt>xsd:double</tt> or a SOAP Fault
</td></tr></table>

</td></tr></table><br></span>
The <i>soapcpp2</i> compile generates a WSDL file for this service, see Section&nbsp;<a href="#sec:wsdl">7.2.9</a>.

<div class="p"><!----></div>
Unless the CGI application inspects and checks the environment variable <i>SOAPAction</i> which contains the SOAP action request by
a client, the SOAP action is ignored by the CGI application.  SOAP actions are specific to the SOAP protocol and provide a means
for routing requests and for security reasons (e.g.&nbsp;firewall software can inspect SOAP action headers to grant or deny the
SOAP request. Note that this requires the SOAP service to check the SOAP action header as well to match it with the service operation.)

<div class="p"><!----></div>
The header file input to the gSOAP <i>soapcpp2</i> compiler does not need to be modified to generate client stubs for accessing this
service.  Client applications can be developed by using the same header file as for which the service application
was developed.  For example, the <i>soap_call_ns__add</i> stub routine is available from the <i>soapClient.cpp</i> file after invoking
the gSOAP <i>soapcpp2</i> compiler on the <i>calc.h</i> header file. As a result, client and service applications can be developed without
the need to know the details of the SOAP encoding used.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.2">
7.2.2</a>&nbsp;&nbsp;<font color="#0000FF">MSVC++ Builds</font></h4>

<div class="p"><!----></div>

<ul>
<li> Win32 builds need winsock2 (MS Visual C++ "ws2_32.lib")
To do this in Visual C++ 6.0, go to "Project", "settings", select the "Link"
tab (the project file needs to be selected in the file view) and add
"<i>ws2_32.lib</i>" to the "<i>Object/library modules</i>" entry.
<div class="p"><!----></div>
</li>

<li> Use files with extension .cpp only (don't mix .c with .cpp).
<div class="p"><!----></div>
</li>

<li> Turn pre-compiled headers off.
<div class="p"><!----></div>
</li>

<li> When creating a new project, you can specify a custom build step to automatically invoke the gSOAP <i>soapcpp2</i> compiler on a gSOAP header file. In this way you can incrementally build a new service by adding new operations and data types to the header file. To specify a custom build step, select the "Project" menu item "Settings" and select the header file in the File view pane. Select the "Custom Build" tab and enter '<i>soapcpp2.exe "$(inputPath)"</i>' in the "Command" pane. Enter '<i>soapStub.h soapH.h soapC.cpp soapClient.cpp soapServer.cpp</i>'. Don't forget to add the <i>soapXYZProxy.h soapXYZObject.h</i> files that are generated for C++ class proxies and server objects named XYZ. Click "OK". Run <i>soapcpp2</i> once to generate these files (you can simply do this by selecting your header file and select "Compile"). Add the files to your project. Each time you make a change to the header file, the project sources are updated automatically.
<div class="p"><!----></div>
</li>

<li> You may want to use the WinInet interface available in the <i>mod_gsoap</i> directory of the gSOAP package to simplify Internet access and deal with encryption, proxies, and authentication. API instructions are included in the source.
<div class="p"><!----></div>
</li>

<li> For the PocketPC, run the <i>wsdl2h</i> WSDL parser with option <i>-s</i> to prevent the generation of STL code. In addition, <i>time_t</i> serialization is not supported, which means that you should add the following line to <i>typemap.dat</i> indicating a mapping of <i>xsd__dateTime</i> to <i><b>char</b>*</i>: <tt>xsd__dateTime =  -  char*  -  char*</tt>.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.3">
7.2.3</a>&nbsp;&nbsp;<font color="#0000FF">How to Create a Stand-Alone Server</font></h4><a name="sec:stand-alone">
</a>

<div class="p"><!----></div>
The deployment of a Web service as a CGI application is an easy means to
provide your service on the Internet. However, the performance of CGI is not
great.  Also, gSOAP services can be run as stand-alone services on any port by
utilizing the built-in HTTP and TCP/IP stacks.  However, the preferred
mechanism to deploy a service is through an Apache module or IIS module. These
servers and modules are designed for server load balancing and access control.

<div class="p"><!----></div>
To create a stand-alone service, only the <i>main</i> routine of the service needs to be modified as follows.  Instead of just calling the
<i>soap_serve</i> routine, the <i>main</i> routine is changed into:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{<br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;m, s; // master and slave sockets <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;m = soap_bind(&amp;soap, <tt>"machine.genivia.com"</tt>, 18083, 100); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(m  &lt;  0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Socket&nbsp;connection&nbsp;successful:&nbsp;master&nbsp;socket&nbsp;=&nbsp;%d\n"</tt>, m); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(<b>int</b>&nbsp;i = 1; ; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s = soap_accept(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(s  &lt;  0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;break; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"%d:&nbsp;accepted&nbsp;connection&nbsp;from&nbsp;IP=%d.%d.%d.%d&nbsp;socket=%d"</tt>, i, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(soap.ip &gt;&gt; 24)&amp;0xFF, (soap.ip &gt;&gt; 16)&amp;0xFF, (soap.ip &gt;&gt; 8)&amp;0xFF, soap.ip&amp;0xFF, s); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_serve(&amp;soap) != SOAP_OK)	// process RPC request <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // print error <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"request&nbsp;served\n"</tt>); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_destroy(&amp;soap);	// clean up class instances <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_end(&amp;soap);	// clean up everything and close socket <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); // close master socket and detach context <br />
}
</td></tr></table><br></i>
The <i>soap_serve</i> dispatcher handles one request or multiple requests when HTTP keep-alive is enabled (with the <i>SOAP_IO_KEEPALIVE</i> flag see Section&nbsp;<a href="#sec:keepalive">19.11</a>).

<div class="p"><!----></div>
The gSOAP functions that are frequently used for server-side coding are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>soap_new()</i> </td><td align="left">Allocates and Initializes gSOAP context </td></tr>
<tr><td align="left"><i>soap_init(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Initializes a stack-allocated gSOAP context (required once) </td></tr>
<tr><td align="left"><i>soap_bind(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*host, <b>int</b>&nbsp;port, <b>int</b>&nbsp;backlog)</i> </td><td align="left">Returns master socket (backlog = max.&nbsp;queue
size for requests). When <i>host==NULL</i>: host is the machine on which the service runs </td></tr>
<tr><td align="left"><i>soap_accept(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Returns slave socket </td></tr>
<tr><td align="left"><i>soap_end(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Clean up deserialized data (except class instances) and temporary data </td></tr>
<tr><td align="left"><i>soap_free_temp(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Clean up temporary data only </td></tr>
<tr><td align="left"><i>soap_destroy(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Clean up deserialized class instances (note: this function will be renamed with option <i>-n</i> </td></tr>
<tr><td align="left"><i>soap_done(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Reset and detach context: close master/slave sockets and remove callbacks </td></tr>
<tr><td align="left"><i>soap_free(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Detach and deallocate context (<i>soap_new</i>()) </td></tr></table>

</td></tr></table><br></span>
The <i>host</i> name in <i>soap_bind</i> may be NULL to indicate that the current host should be used.

<div class="p"><!----></div>
The <i>soap.accept_timeout</i> attribute of the gSOAP runtime context specifies the timeout value for a non-blocking
<i>soap_accept(&amp;soap)</i> call. See Section&nbsp;<a href="#sec:timeout">19.19</a> for more details on timeout management.

<div class="p"><!----></div>
See Section&nbsp;<a href="#sec:memory">9.13</a> for more details on memory management.

<div class="p"><!----></div>
A client application connects to this stand-alone service with the endpoint
<i>machine.genivia.com:18083</i>.
A client may use the <i>http://</i> prefix. When absent, no HTTP header is sent
and no HTTP-based information will be communicated to the service.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.4">
7.2.4</a>&nbsp;&nbsp;<font color="#0000FF">How to Create a Multi-Threaded Stand-Alone Service</font></h4><a name="sec:mt">
</a>

<div class="p"><!----></div>
Stand-alone multi-threading a Web Service is essential when the response times for handling requests by the service are (potentially) long or when keep-alive is enabled, see Section&nbsp;<a href="#sec:keepalive">19.11</a>.
In case of long response times, the latencies introduced by the unrelated
requests may become prohibitive for a successful deployment of a stand-alone
service. When HTTP keep-alive is enabled, a client may not close the socket on
time, thereby preventing other clients from connecting.

<div class="p"><!----></div>
However, the preferred mechanism to deploy a service is through an Apache
module or IIS module. These servers and modules are designed for server load
balancing and access control.

<div class="p"><!----></div>
The following example illustrates the use of threads to improve the quality of service by handling new requests in separate threads:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
#include  &lt; pthread.h &gt;  <br />
#define BACKLOG (100)	// Max. request backlog <br />
<b>int</b>&nbsp;main(<b>int</b>&nbsp;argc, <b>char</b>&nbsp;**argv) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(argc  &lt;  2) // no args: assume this is a CGI application <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_serve(&amp;soap); // serve request, one thread, CGI style <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_destroy(&amp;soap); // dealloc C++ data <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); // dealloc data and clean up <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.send_timeout = 60; // 60 seconds <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.recv_timeout = 60; // 60 seconds <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.accept_timeout = 3600; // server stops after 1 hour of inactivity <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.max_keep_alive = 100; // max keep-alive sequence <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>void</b>&nbsp;*process_request(<b>void</b>*); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap *tsoap; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_t tid; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;port = atoi(argv[1]); // first command-line arg is port <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SOAP_SOCKET m, s; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;m = soap_bind(&amp;soap, NULL, port, BACKLOG); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_valid_socket(m)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Socket&nbsp;connection&nbsp;successful&nbsp;%d\n"</tt>, m); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(;;) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s = soap_accept(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_valid_socket(s)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap.errnum) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"server&nbsp;timed&nbsp;out\n"</tt>); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Thread&nbsp;%d&nbsp;accepts&nbsp;socket&nbsp;%d&nbsp;connection&nbsp;from&nbsp;IP&nbsp;%d.%d.%d.%d\n"</tt>, i, s, (soap.ip &gt;&gt; 24)&amp;0xFF,
(soap.ip &gt;&gt; 16)&amp;0xFF, (soap.ip &gt;&gt; 8)&amp;0xFF, soap.ip&amp;0xFF); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tsoap = soap_copy(&amp;soap); // make a safe copy <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!tsoap) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_create(&amp;tid, NULL, (<b>void</b>*(*)(<b>void</b>*))process_request, (<b>void</b>*)tsoap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); // detach soap struct <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
} <br />
<b>void</b>&nbsp;*process_request(<b>void</b>&nbsp;*soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;pthread_detach(pthread_self()); <br />
&nbsp;&nbsp;&nbsp;soap_serve((<b>struct</b>&nbsp;soap*)soap); <br />
&nbsp;&nbsp;&nbsp;soap_destroy((<b>struct</b>&nbsp;soap*)soap); // dealloc C++ data <br />
&nbsp;&nbsp;&nbsp;soap_end((<b>struct</b>&nbsp;soap*)soap); // dealloc data and clean up <br />
&nbsp;&nbsp;&nbsp;soap_done((<b>struct</b>&nbsp;soap*)soap); // detach soap struct <br />
&nbsp;&nbsp;&nbsp;free(soap); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;NULL; <br />
}
</td></tr></table><br></i>
Note: the code does not wait for threads to join the main thread upon program termination.

<div class="p"><!----></div>
The <i>soap_serve</i> dispatcher handles one request or multiple requests when
HTTP keep-alive is set with <i>SOAP_IO_KEEPALIVE</i>. The
<i>soap.max_keep_alive</i> value can be set to the maximum keep-alive calls
allowed, which is important to avoid a client from holding a thread
indefinitely. The send and receive timeouts are set to avoid (intentionally)
slow clients from holding a socket connection too long. The accept timeout is used
to let the server terminate automatically after a period of inactivity.

<div class="p"><!----></div>
The following example uses a pool of servers to limit the machine's resource utilization:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
#include  &lt; pthread.h &gt;  <br />
#define BACKLOG (100)	// Max. request backlog <br />
#define MAX_THR (10)	// Max. threads to serve requests <br />
<b>int</b>&nbsp;main(<b>int</b>&nbsp;argc, <b>char</b>&nbsp;**argv) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(argc  &lt;  2) // no args: assume this is a CGI application <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_serve(&amp;soap); // serve request, one thread, CGI style <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_destroy(&amp;soap); // dealloc C++ data <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); // dealloc data and clean up <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap *soap_thr[MAX_THR]; // each thread needs a runtime context <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_t tid[MAX_THR]; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;port = atoi(argv[1]); // first command-line arg is port <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SOAP_SOCKET m, s; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;i; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;m = soap_bind(&amp;soap, NULL, port, BACKLOG); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_valid_socket(m)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Socket&nbsp;connection&nbsp;successful&nbsp;%d\n"</tt>, m); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  MAX_THR; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_thr[i] = NULL; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(;;) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  MAX_THR; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s = soap_accept(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_valid_socket(s)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap.errnum) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>continue</b>; // retry<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Server&nbsp;timed&nbsp;out\n"</tt>); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Thread&nbsp;%d&nbsp;accepts&nbsp;socket&nbsp;%d&nbsp;connection&nbsp;from&nbsp;IP&nbsp;%d.%d.%d.%d\n"</tt>, i, s, (soap.ip &gt;&gt; 24)&amp;0xFF,
(soap.ip &gt;&gt; 16)&amp;0xFF, (soap.ip &gt;&gt; 8)&amp;0xFF, soap.ip&amp;0xFF); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_thr[i]) // first time around <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_thr[i] = soap_copy(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_thr[i]) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); // could not allocate <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>else</b>// recycle soap context <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_join(tid[i], NULL); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, "Thread <tt>%</tt>d completed<tt>\</tt>n", i); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_destroy(soap_thr[i]); // deallocate C++ data of old thread <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_end(soap_thr[i]); // deallocate data of old thread <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_thr[i]<tt>-&gt;</tt>socket = s; // new socket fd <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_create(&amp;tid[i], NULL, (<b>void</b>*(*)(<b>void</b>*))soap_serve, (<b>void</b>*)soap_thr[i]); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  MAX_THR; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_thr[i]) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_done(soap_thr[i]); // detach context <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;free(soap_thr[i]); // free up <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
}
</td></tr></table><br></i>
The following functions can be used to setup a gSOAP runtime context (<i><b>struct</b>&nbsp;soap</i>):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>soap_init(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Initializes a runtime context (required only once) </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap *soap_new()</i> </td><td align="left">Allocates, initializes, and returns a pointer to a runtime context </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap *soap_copy(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Allocates a new runtime context and copies a context (deep copy, i.e.&nbsp;the new context does not share any data with the other context) </td></tr>
<tr><td align="left">the argument context such that the new context does not share data with the argument context </td></tr>
<tr><td align="left"><i>soap_done(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Reset, close communications, and remove callbacks </td></tr></table>

</td></tr></table><br></span>
A new context is initiated for each thread to guarantee exclusive access
to runtime contexts.

<div class="p"><!----></div>
For clean termination of the server, the master socket can be closed and callbacks removed with <i>soap_done(<b>struct</b>&nbsp;soap *soap)</i>.

<div class="p"><!----></div>
The advantage of the code shown above is that the machine cannot be overloaded with requests, since the number of active services is limited. However, threads are still started and terminated. This overhead can be eliminated using a queue of requests (open sockets) as is shown in the code below.

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
#include  &lt; pthread.h &gt;  <br />
#define BACKLOG (100)	// Max. request backlog <br />
#define MAX_THR (10) // Size of thread pool <br />
#define MAX_QUEUE (1000) // Max. size of request queue <br />
SOAP_SOCKET queue[MAX_QUEUE]; // The global request queue of sockets <br />
<b>int</b>&nbsp;head = 0, tail = 0; // Queue head and tail <br />
<b>void</b>&nbsp;*process_queue(<b>void</b>*); <br />
<b>int</b>&nbsp;enqueue(SOAP_SOCKET); <br />
SOAP_SOCKET dequeue(); <br />
pthread_mutex_t queue_cs; <br />
pthread_cond_t queue_cv; <br />
<b>int</b>&nbsp;main(<b>int</b>&nbsp;argc, <b>char</b>&nbsp;**argv) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(argc  &lt;  2) // no args: assume this is a CGI application <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_serve(&amp;soap); // serve request, one thread, CGI style <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_destroy(&amp;soap); // dealloc C++ data <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); // dealloc data and clean up <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap *soap_thr[MAX_THR]; // each thread needs a runtime context <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_t tid[MAX_THR]; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;port = atoi(argv[1]); // first command-line arg is port <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SOAP_SOCKET m, s; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;i; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;m = soap_bind(&amp;soap, NULL, port, BACKLOG); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_valid_socket(m)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Socket&nbsp;connection&nbsp;successful&nbsp;%d\n"</tt>, m); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_mutex_init(&amp;queue_cs, NULL); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_cond_init(&amp;queue_cv, NULL); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  MAX_THR; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_thr[i] = soap_copy(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Starting&nbsp;thread&nbsp;%d\n"</tt>, i); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_create(&amp;tid[i], NULL, (<b>void</b>*(*)(<b>void</b>*))process_queue, (<b>void</b>*)soap_thr[i]); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(;;) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s = soap_accept(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_valid_socket(s)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap.errnum) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>continue</b>; // retry <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Server&nbsp;timed&nbsp;out\n"</tt>); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Thread&nbsp;%d&nbsp;accepts&nbsp;socket&nbsp;%d&nbsp;connection&nbsp;from&nbsp;IP&nbsp;%d.%d.%d.%d\n"</tt>, i, s, (soap.ip &gt;&gt; 24)&amp;0xFF, (soap.ip &gt;&gt; 16)&amp;0xFF, (soap.ip &gt;&gt; 8)&amp;0xFF, soap.ip&amp;0xFF); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>while</b>&nbsp;(enqueue(s) == SOAP_EOM) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sleep(1); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  MAX_THR; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>while</b>&nbsp;(enqueue(SOAP_INVALID_SOCKET) == SOAP_EOM) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sleep(1); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  MAX_THR; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Waiting&nbsp;for&nbsp;thread&nbsp;%d&nbsp;to&nbsp;terminate...&nbsp;"</tt>, i); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_join(tid[i], NULL); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"terminated\n"</tt>); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_done(soap_thr[i]); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;free(soap_thr[i]); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_mutex_destroy(&amp;queue_cs); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_cond_destroy(&amp;queue_cv); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
} <br />
<b>void</b>&nbsp;*process_queue(<b>void</b>&nbsp;*soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap *tsoap = (<b>struct</b>&nbsp;soap*)soap; <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(;;) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tsoap<tt>-&gt;</tt>socket = dequeue(); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_valid_socket(tsoap<tt>-&gt;</tt>socket)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_serve(tsoap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_destroy(tsoap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_end(tsoap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"served\n"</tt>); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;NULL; <br />
} <br />
<b>int</b>&nbsp;enqueue(SOAP_SOCKET sock) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;status = SOAP_OK; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;next; <br />
&nbsp;&nbsp;&nbsp;pthread_mutex_lock(&amp;queue_cs); <br />
&nbsp;&nbsp;&nbsp;next = tail + 1; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(next <tt>&gt;=</tt> MAX_QUEUE) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;next = 0; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(next <tt>==</tt> head) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;status = SOAP_EOM; <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;queue[tail] = sock; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tail = next; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_cond_signal(&amp;queue_cv); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;pthread_mutex_unlock(&amp;queue_cs); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;status; <br />
} <br />
SOAP_SOCKET dequeue() <br />
{ <br />
&nbsp;&nbsp;&nbsp;SOAP_SOCKET sock; <br />
&nbsp;&nbsp;&nbsp;pthread_mutex_lock(&amp;queue_cs); <br />
&nbsp;&nbsp;&nbsp;<b>while</b>&nbsp;(head == tail) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_cond_wait(&amp;queue_cv, &amp;queue_cs); <br />
&nbsp;&nbsp;&nbsp;sock = queue[head++]; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(head <tt>&gt;=</tt> MAX_QUEUE) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;head = 0; <br />
&nbsp;&nbsp;&nbsp;pthread_mutex_unlock(&amp;queue_cs); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;sock; <br />
}
</td></tr></table><br></i>
Note: the <i>plugin/threads.h</i> and <i>plugin/threads.c</i> code can be used
for a portable implementation. Instead of POSIX calls, use <i>MUTEX_LOCK</i>,
<i>MUTEX_UNLOCK</i>, and <i>COND_WAIT</i>. These are wrappers for Win API calls
or POSIX calls.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.5">
7.2.5</a>&nbsp;&nbsp;<font color="#0000FF">How to Pass Application Data to Service Methods</font></h4>

<div class="p"><!----></div>
The <i><b>void</b>&nbsp;*soap.user</i> field can be used to pass application data to
service methods. This field should be set before the <i>soap_serve()</i> call.
The service method can access this field to use the application-dependent data.
The following example shows how a non-static database handle is initialized and
passed to the service methods:

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
{ ... <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;database_handle_type database_handle; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap);
&nbsp;&nbsp;&nbsp;soap.user = (void*)database_handle; <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_serve(&amp;soap); // call the service operation dispatcher to handle request <br />
&nbsp;&nbsp;&nbsp;... <br />
} <br />
<b>int</b>&nbsp;ns__myMethod(<b>struct</b>&nbsp;soap *soap, ...) <br />
{ ... <br />
&nbsp;&nbsp;&nbsp;fetch((database_handle_type*)soap<tt>-&gt;</tt>user); <br />// get data
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
Another way to pass application data around in a more organized way is accomplished with plugins, see Section&nbsp;<a href="#sec:plugins">19.38</a>.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.6">
7.2.6</a>&nbsp;&nbsp;<font color="#0000FF">Web Service Implementation Aspects</font></h4>

<div class="p"><!----></div>
The same client header file specification issues apply to the specification and implementation of a SOAP Web service. Refer to

<ul>
<li> <a href="#sec:namespace">7.1.2</a> for namespace considerations.
<div class="p"><!----></div>
</li>

<li> <a href="#sec:encoding">7.1.5</a> for an explanation on how to change the encoding of the primitive types.
<div class="p"><!----></div>
</li>

<li> <a href="#sec:response">7.1.7</a> for a discussion on how the response element format can be controlled.
<div class="p"><!----></div>
</li>

<li> <a href="#sec:multiple">7.1.9</a> for details on how to pass multiple output parameters from a service operation.
<div class="p"><!----></div>
</li>

<li> <a href="#sec:compound">7.1.11</a> for passing complex data types as output parameters.
<div class="p"><!----></div>
</li>

<li> <a href="#sec:anonymous">7.1.13</a> for anonymizing the input and output parameter names.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.7">
7.2.7</a>&nbsp;&nbsp;<font color="#0000FF">How to Generate C++ Server Object Classes</font></h4><a name="sec:object">
</a>

<div class="p"><!----></div>
Server object classes for C++ server applications are automatically generated
by the gSOAP <i>soapcpp2</i> compiler.

<div class="p"><!----></div>
There are two modes for generating classes. Use <i>soapcpp2</i> option <i>-i</i>
(or <i>-j</i>) to generate improved class definitions where the class' member
functions are the service methods.

<div class="p"><!----></div>
The older examples (without the use of <i>soapcpp2</i> option <i>-i</i> and
<i>-j</i>) use a C-like approach with globally defined service methods,
which is illustated here with a calculator example:

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Content of file <tt>"calc.h"</tt>: <br />
//gsoap ns service name: Calculator <br />
//gsoap ns service protocol: SOAP <br />
//gsoap ns service style: rpc <br />
//gsoap ns service encoding: encoded <br />
//gsoap ns service location: http://www.cs.fsu.edu/~engelen/calc.cgi <br />
//gsoap ns schema namespace: urn:calc <br />
//gsoap ns service method-action: add "" <br />
<b>int</b>&nbsp;ns__add(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
<b>int</b>&nbsp;ns__sub(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
<b>int</b>&nbsp;ns__mul(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
<b>int</b>&nbsp;ns__div(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result);
</td></tr></table><br></i>
The first three directives provide the service name which is used to name the service class, the service location (endpoint), and
the schema. The fourth directive defines the optional SOAPAction for the method, which is a string associated with SOAP 1.1 operations.
Compilation of this header file with <i>soapcpp2 -i</i> creates a new file <i>soapCalculatorObject.h</i> with the
following contents:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
<b>class</b>&nbsp;CalculatorObject : <b>public</b>&nbsp;soap <br />
{ <b>public</b>: <br />
&nbsp;&nbsp;&nbsp;Calculator() { ... }; <br />
&nbsp;&nbsp;&nbsp;~Calculator() { ... }; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;serve() { <b>return</b>&nbsp;soap_serve(<b>this</b>); }; <br />
};
</td></tr></table><br></i>
This generated server object class can be included into a server application together with the generated namespace table as shown in this example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapCalculatorObject.h"	// get server object <br />
#include "Calculator.nsmap"		// get namespace bindings <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;CalculatorObject c; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;c.serve(); // calls <i>soap_serve</i> to serve as CGI application (using stdin/out) <br />
} <br />
// C-style global functions implement server operations (soapcpp2 w/o option -i)<br />
<b>int</b>&nbsp;ns__add(<b>struct</b>&nbsp;soap *soap, <b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result) <br />
{ <br />
&nbsp;&nbsp;&nbsp;result = a + b; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
... sub(), mul(), and div() implementations ...
</td></tr></table><br></i>
You can use <i>soapcpp2</i> option <i>-n</i> together with <i>-p</i> to create a
local namespace table to avoid link conflict when you need to combine multiple
tables and/or multiple servers, see also Sections&nbsp;<a href="#sec:options">9.1</a>
and&nbsp;<a href="#sec:dylibs">19.36</a>, and you can use a C++ code <i><b>namespace</b></i> to create a
namespace qualified server object class, see Section&nbsp;<a href="#sec:codenamespace">19.35</a>.

<div class="p"><!----></div>
The example above serves requests over stdin/out. Use the bind and accept calls
to create a stand-alone server to service inbound requests over sockets, see
also&nbsp;<a href="#sec:stand-alone">7.2.3</a>.

<div class="p"><!----></div>
A better alternative is to use the <i>soapcpp2</i> option <i>-i</i>. The C++ proxy and server objects are
derived from the soap context struct, which simplifies the proxy invocation and
service operation implementations.

<div class="p"><!----></div>
Compilation of the above header file with the gSOAP compiler <i>soapcpp2</i> option <i>-i</i> creates new files <i>soapCalculatorService.h</i> and <i>soapCalculatorService.cpp</i> (rather than the C-style <i>soapServer.cpp</i>).

<div class="p"><!----></div>
This generated server object class can be included into a server application together with the generated namespace table as shown in this example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapCalculatorService.h"	// get server object <br />
#include "Calculator.nsmap"		// get namespace bindings <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;soapCalculatorService c; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;c.serve(); // calls <i>soap_serve</i> to serve as CGI application (using stdin/out) <br />
} <br />
// The 'add' service method (soapcpp2 w/ option -i) <br />
<b>int</b>&nbsp;soapCalculatorService::add(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result) <br />
{ <br />
&nbsp;&nbsp;&nbsp;result = a + b; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
... sub(), mul(), and div() implementations ...
</td></tr></table><br></i>
Note that the service operation does not need a prefix (<i>ns__</i>) and there
is no soap context struct passed to the service operation since the service
object itself is the context (it is derived from the soap struct).

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.8">
7.2.8</a>&nbsp;&nbsp;<font color="#0000FF">How to Chain C++ Server Classes to Accept Messages on the Same Port</font></h4><a name="sec:chaining">
</a>

<div class="p"><!----></div>
When combining multiple services into one application, you can run <i>wsdl2h</i>
on multiple WSDLs to generate the single all-inclusive service definitions
header file. This header file is then processed with <i>soapcpp2</i>, for
example to generate server class objects with option <i>-i</i> and <i>-q</i> to separate the service codes with C++ namespaces, see Section&nbsp;<a href="#sec:codenamespace">19.35</a>.

<div class="p"><!----></div>
This works well, but the problem is that we end up with multiple classes, each
for a collection of service operations the class is supposed to implement. But
what if we need to provide one endpoint port for all services and operations?
In this case invoking the server object's <i>serve</i> method is not sufficient, since only one
service can accept requests while we want multiple services to listen to the
same port.

<div class="p"><!----></div>
The approach is to chain the service dispatchers, as shown below:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
Abc::soapABCService abc; // generated with soapcpp2 -i -S -qAbc <br />
Uvw::soapUVWService uvw; // generated with soapcpp2 -i -S -qUvw <br />
Xyz::soapXYZService xyz; // generated with soapcpp2 -i -S -qXyz <br />
... <br />
abc.bind(NULL, 8080, 100); <br />
... <br />
abc.accept(); <br />
// when using SSL: ssl_accept(&amp;abc); <br />
... <br />
<b>if</b>(soap_begin_serve(&amp;abc)) // available in 2.8.2 and later <br />
&nbsp;&nbsp;&nbsp;abc.soap_stream_fault(std::cerr); <br />
<b>else</b><b>if</b>&nbsp;(abc.dispatch() == SOAP_NO_METHOD) <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_copy_stream(&amp;uvw, &amp;abc); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(uvw.dispatch() == SOAP_NO_METHOD) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_copy_stream(&amp;xyz, &amp;uvw); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(xyz.dispatch()) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_send_fault(&amp;xyz); // send fault to client <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xyz.soap_stream_fault(std::cerr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_free_stream(&amp;xyz); // free the copy <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xyz.destroy(); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_send_fault(&amp;uvw); // send fault to client <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;uvw.soap_stream_fault(std::cerr); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap_free_stream(&amp;uvw); // free the copy <br />
&nbsp;&nbsp;&nbsp;uvw.destroy(); <br />
} <br />
<b>else</b><br />
&nbsp;&nbsp;&nbsp;abc.soap_stream_fault(std::cerr); <br />
abc.destroy(); <br />
...
</td></tr></table><br></i>
The <i>dispatch</i> method parses the SOAP/XML request and invokes the service
operations, unless there is no matching operation and <i>SOAP_NO_METHOD</i> is
returned. The <i>soap_copy_stream</i> ensures that the service object uses the
currently open socket. The copied streams are freed with
<i>soap_free_stream</i>. Do not enable keep-alive support, as the socket may
stay open indefinitely afterwards as a consequence. Also, the <i>dispatch</i>
method does not send a fault to the client, which has to be explicitly done
with the <i>soap_send_fault</i> operation when an error occurs.

<div class="p"><!----></div>
In this way, multiple services can be chained to accept messages on the same port. This approach also works with SSL for HTTPS services.

<div class="p"><!----></div>
However, this approach is not recommended for certain plugins, because plugins
must be registered with all service objects and some plugins require state
information to be used across the service objects, which will add significantly
to the complexity.

<div class="p"><!----></div>
When plugin complications arise, it is best to have all services share the same
context. This means that <i>soapcpp2</i> option <i>-j</i> should be used instead of option <i>-i</i>.
Each service class has a pointer member to a soap struct
context. This member pointer should point to the same soap context.

<div class="p"><!----></div>
With option <i>-j</i> and <i>-q</i> the code to chain the services is as follows, based on a single <i><b>struct</b>&nbsp;soap</i> engine context:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap *soap = soap_new(); <br />
Abc::soapABCService abc(soap); // generated with soapcpp2 -j -S -qAbc <br />
Uvw::soapUVWService uvw(soap); // generated with soapcpp2 -j -S -qUvw <br />
Xyz::soapXYZService xyz(soap); // generated with soapcpp2 -j -S -qXyz <br />
<br />
soap_bind(soap, NULL, 8080, 100); <br />
soap_accept(soap); <br />
<b>if</b>&nbsp;(soap_begin_serve(soap)) <br />
&nbsp;&nbsp;&nbsp;... error <br />
<b>else</b>&nbsp;<b>if</b>&nbsp;(abc.dispatch() == SOAP_NO_METHOD) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(uvw.dispatch() == SOAP_NO_METHOD) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(xyz.dispatch() == SOAP_NO_METHOD) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... error <br />
&nbsp;&nbsp;&nbsp;} <br />
} <br />
soap_destroy(soap); <br />
soap_end(soap); <br />
soap_free(soap); // only safe when abc, uvw, xyz are also deleted
</td></tr></table><br></i>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.9">
7.2.9</a>&nbsp;&nbsp;<font color="#0000FF">How to Generate WSDL Service Descriptions</font></h4><a name="sec:wsdl">
</a>

<div class="p"><!----></div>
The gSOAP stub and skeleton compiler <i>soapcpp2</i> generates WSDL (Web Service Description Language) service descriptions and XML Schema files
when processing a header file.  The tool produces one WSDL file for a set of service operations, which must be provided.  The names of the function
prototypes of the service operations must use the same namespace prefix and the namespace prefix is used to name the WSDL file.  If
multiple namespace prefixes are used to define service operations, multiple WSDL files will be created and each file describes the set
of service operations belonging to a namespace prefix.

<div class="p"><!----></div>
In addition to the generation of the <tt>ns.wsdl</tt> file, a file with a namespace mapping table is generated by the gSOAP
compiler. An example mapping table is shown below:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{ <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/"}, <br />
&nbsp;&nbsp;&nbsp;{"xsi", "http://www.w3.org/2001/XMLSchema-instance", \"http://www.w3.org/*/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd", "http://www.w3.org/2001/XMLSchema", \"http://www.w3.org/*/XMLSchema"}, <br />
&nbsp;&nbsp;&nbsp;{"ns", "http://tempuri.org"}, <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} <br />
};
</td></tr></table><br></i>
This file can be incorporated in the
client/service application, see Section&nbsp;<a href="#sec:nstable">10.4</a> for details on namespace mapping tables.

<div class="p"><!----></div>
To deploy a Web service, copy the compiled CGI service application to the designated CGI directory of your Web server.
Make sure the proper file permissions are set (<tt>chmod 755 calc.cgi</tt> for Unix/Linux).
You can then publish the WSDL file on the Web by placing it in the appropriate Web server directory.

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> compiler also generates XML Schema files for all C/C++
complex types (e.g.&nbsp;<i><b>struct</b></i>s and <i><b>class</b></i>es) when declared with a namespace prefix.
These files are named <tt>ns.xsd</tt>, where <tt>ns</tt> is the namespace prefix used in the declaration of the complex type.
The XML Schema files do not have to be published as the WSDL file already contains the appropriate XML Schema definitions.

<div class="p"><!----></div>
To customize the WSDL output, it is essential to use <i>//gsoap</i> directives to declare the service name, the endpoint port, and namespace:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service name: example <br />
//gsoap ns servire port: http://www.mydomain.com/example <br />
//gsoap ns service namespace: urn:example
</td></tr></table><br></i>
These are minimal settings. More details and settings for the service operations should be declared as well. See Section&nbsp;<a href="#sec:directives">19.2</a> for more details.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.10">
7.2.10</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4><a name="sec:example8">
</a>

<div class="p"><!----></div>
For example, suppose the following methods are defined in the header file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>double</b>&nbsp;xsd__double; <br />
<b>int</b>&nbsp;ns__add(xsd__double a, xsd__double b, xsd__double &amp;result); <br />
<b>int</b>&nbsp;ns__sub(xsd__double a, xsd__double b, xsd__double &amp;result); <br />
<b>int</b>&nbsp;ns__sqrt(xsd__double a, xsd__double &amp;result); <br />
</td></tr></table><br></i>
Then, one WSDL file will be created with the file name <tt>ns.wsdl</tt> that describes all three service operations:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;?xml version="1.0" encoding="UTF-8"?&#62; <br />
&lt;definitions name="Service" <br />
&nbsp;&nbsp;&nbsp;xmlns="http://schemas.xmlsoap.org/wsdl/" <br />
&nbsp;&nbsp;&nbsp;targetNamespace="http://location/Service.wsdl" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/" <br />
&nbsp;&nbsp;&nbsp;xmlns:WSDL="http://schemas.xmlsoap.org/wsdl/" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsd="http://www.w3.org/2000/10/XMLSchema" <br />
&nbsp;&nbsp;&nbsp;xmlns:tns="http://location/Service.wsdl" <br />
&nbsp;&nbsp;&nbsp;xmlns:ns="http://tempuri.org"&#62; <br />
&lt;types&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;schema <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xmlns="http://www.w3.org/2000/10/XMLSchema" <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;targetNamespace="http://tempuri.org" <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;complexType name="addResponse"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;all&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="result" type="double" minOccurs="0" maxOccurs="1"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/all&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;anyAttribute namespace="##other"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/complexType&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;complexType name="subResponse"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;all&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="result" type="double" minOccurs="0" maxOccurs="1"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/all&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;anyAttribute namespace="##other"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/complexType&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;complexType name="sqrtResponse"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;all&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="result" type="double" minOccurs="0" maxOccurs="1"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/all&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;anyAttribute namespace="##other"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/complexType&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/schema&#62; <br />
&lt;/types&#62; <br />
&lt;message name="addRequest"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;part name="a" type="xsd:double"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;part name="b" type="xsd:double"/&#62; <br />
&lt;/message&#62; <br />
&lt;message name="addResponse"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;part name="result" type="xsd:double"/&#62; <br />
&lt;/message&#62; <br />
&lt;message name="subRequest"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;part name="a" type="xsd:double"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;part name="b" type="xsd:double"/&#62; <br />
&lt;/message&#62; <br />
&lt;message name="subResponse"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;part name="result" type="xsd:double"/&#62; <br />
&lt;/message&#62; <br />
&lt;message name="sqrtRequest"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;part name="a" type="xsd:double"/&#62; <br />
&lt;/message&#62; <br />
&lt;message name="sqrtResponse"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;part name="result" type="xsd:double"/&#62; <br />
&lt;/message&#62; <br />
&lt;portType name="ServicePortType"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;operation name="add"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;input message="tns:addRequest"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;output message="tns:addResponse"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/operation&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;operation name="sub"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;input message="tns:subRequest"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;output message="tns:subResponse"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/operation&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;operation name="sqrt"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;input message="tns:sqrtRequest"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;output message="tns:sqrtResponse"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/operation&#62; <br />
&lt;/portType&#62; <br />
&lt;binding name="ServiceBinding" type="tns:ServicePortType"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;SOAP:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;operation name="add"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;SOAP:operation soapAction="http://tempuri.org#add"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;input&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;SOAP:body use="encoded" namespace="http://tempuri.org" <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/input&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;output&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;SOAP:body use="encoded" namespace="http://tempuri.org" <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/output&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/operation&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;operation name="sub"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;SOAP:operation soapAction="http://tempuri.org#sub"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;input&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;SOAP:body use="encoded" namespace="http://tempuri.org" <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/input&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;output&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;SOAP:body use="encoded" namespace="http://tempuri.org" <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/output&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/operation&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;operation name="sqrt"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;SOAP:operation soapAction="http://tempuri.org#sqrt"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;input&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;SOAP:body use="encoded" namespace="http://tempuri.org" <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/input&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;output&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;SOAP:body use="encoded" namespace="http://tempuri.org" <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/output&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/operation&#62; <br />
&lt;/binding&#62; <br />
&lt;service name="Service"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;port name="ServicePort" binding="tns:ServiceBinding"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;SOAP:address location="http://location/Service.cgi"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/port&#62; <br />
&lt;/service&#62; <br />
&lt;/definitions&#62;
</td></tr></table><br></tt>
The above uses all default settings for the service name, port, and namespace which should be set in the header file with <i>//gsoap</i> directives (Section&nbsp;<a href="#sec:directives">19.2</a>).

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.2.11">
7.2.11</a>&nbsp;&nbsp;<font color="#0000FF">How to Use Client Functionalities Within a Service</font></h4>

<div class="p"><!----></div>
A gSOAP service implemented with CGI may make direct client calls to other services from within its service operations, without setting up a new context. A stand-alone service application must setup a new soap struct context, e.g.&nbsp;using <i>soap_copy</i> and delete it after the call.

<div class="p"><!----></div>
The server-side client call is best illustrated with an example.  The following example is a
more sophisticated example that combines the functionality of two Web services
into one new SOAP Web service.  The service provides a currency-converted stock
quote.  To serve a request, the service in turn requests the stock quote and
the currency-exchange rate from two XMethods services (these services are no longer available by XMethods, but are used here as an example).

<div class="p"><!----></div>
In addition to being a client of two XMethods services, this service
application can also be used as a client of itself to test the implementation.
As a client invoked from the command-line, it will return a currency-converted
stock quote by connecting to a copy of itself installed as a CGI application on
the Web to retrieve the quote after which it will print the quote on the
terminal.

<div class="p"><!----></div>
The header file input to the gSOAP <i>soapcpp2</i> compiler is given below. The example is for illustrative purposes only (the XMethods services are not operational):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "quotex.h": <br />
<b>int</b>&nbsp;ns1__getQuote(<b>char</b>&nbsp;*symbol, <b>float</b>&nbsp;&amp;result); // XMethods delayed stock quote service service operation <br />
<b>int</b>&nbsp;ns2__getRate(<b>char</b>&nbsp;*country1, <b>char</b>&nbsp;*country2, <b>float</b>&nbsp;&amp;result); // XMethods currency-exchange service service operation <br />
<b>int</b>&nbsp;ns3__getQuote(<b>char</b>&nbsp;*symbol, <b>char</b>&nbsp;*country, <b>float</b>&nbsp;&amp;result); // the new currency-converted stock quote service <br />
</td></tr></table><br></i>
The <i>quotex.cpp</i> client/service application source is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "quotex.cpp": <br />
#include "soapH.h"	// include generated proxy and SOAP support <br />
<b>int</b>&nbsp;main(<b>int</b>&nbsp;argc, <b>char</b>&nbsp;**argv) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>float</b>&nbsp;q; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(argc  &lt; = 2) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_serve(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<b>if</b>&nbsp;(soap_call_ns3__getQuote(&amp;soap, <tt>"http://www.cs.fsu.edu/\symbol{126}engelen/quotex.cgi"</tt>, <tt>""</tt>, argv[1], argv[2], q)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf(<tt>"\nCompany&nbsp;%s:&nbsp;%f&nbsp;(%s)\n"</tt>, argv[1], q, argv[2]); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
} <br />
<b>int</b>&nbsp;ns3__getQuote(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*symbol, <b>char</b>&nbsp;*country, <b>float</b>&nbsp;&amp;result) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>float</b>&nbsp;q, r; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;socket = soap<tt>-&gt;</tt>socket; // save socket (stand-alone service only, does not support keep-alive) <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_ns1__getQuote(soap, <tt>"http://services.xmethods.net/soap"</tt>, <tt>""</tt>, symbol, &amp;q) == 0 &amp;&amp; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_call_ns2__getRate(soap, <tt>"http://services.xmethods.net/soap"</tt>, NULL, <tt>"us"</tt>, country, &amp;r) == 0) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;result = q*r; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>socket = socket; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>socket = socket; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_FAULT;	// pass soap fault messages on to the client of this app <br />
} <br />
/* Since this app is a combined client-server, it is put together with <br />
 * one header file that describes all service operations. However, as a consequence we <br />
 * have to implement the methods that are not ours. Since these implementations are <br />
 * never called (this code is client-side), we can make them dummies as below. <br />
 */ <br />
<b>int</b>&nbsp;ns1__getQuote(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*symbol, <b>float</b>&nbsp;&amp;result) <br />
{ <b>return</b>&nbsp;SOAP_NO_METHOD; } // dummy: will never be called <br />
<b>int</b>&nbsp;ns2__getRate(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*country1, <b>char</b>&nbsp;*country2, <b>float</b>&nbsp;&amp;result) <br />
{ <b>return</b>&nbsp;SOAP_NO_METHOD; } // dummy: will never be called <br />
 <br />
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{ <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/"}, <br />
&nbsp;&nbsp;&nbsp;{"xsi", "http://www.w3.org/2001/XMLSchema-instance", "http://www.w3.org/*/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd", "http://www.w3.org/2001/XMLSchema",          "http://www.w3.org/*/XMLSchema"}, <br />
&nbsp;&nbsp;&nbsp;{"ns1", "urn:xmethods-delayed-quotes"}, <br />
&nbsp;&nbsp;&nbsp;{"ns2", "urn:xmethods-CurrencyExchange"}, <br />
&nbsp;&nbsp;&nbsp;{"ns3", "urn:quotex"}, <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} <br />
};
</td></tr></table><br></i>
To compile:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 quotex.h</i> <br />
<i> &gt;  c++ -o quotex.cgi quotex.cpp soapC.cpp soapClient.cpp soapServer.cpp stdsoap2.cpp -lsocket -lxnet -lnsl</i>
</td></tr></table><br></span>
Note: under Linux and Mac OS X you can often omit the <tt>-l</tt> libraries.

<div class="p"><!----></div>
The <i>quotex.cgi</i> executable is installed as a CGI application on the Web by
copying it in the designated directory specific to your Web server.  After
this, the executable can also serve to test the service.  For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  quotex.cgi IBM uk</i>
</td></tr></table><br></span>
returns the quote of <i>IBM</i> in <i>uk</i> pounds by communicating the request
and response quote from the CGI application.  See
<a href="http://xmethods.com/detail.html?id=5"><tt>http://xmethods.com/detail.html?id=5</tt></a> for details on the currency
abbreviations.

<div class="p"><!----></div>
When combining clients and service functionalities, it is required to use one
header file input to the compiler.  As a consequence, however, stubs and
skeletons are available for <b>all</b> service operations, while the client part
will only use the stubs and the service part will use the skeletons.  Thus,
dummy implementations of the unused service operations need to be given which are
never called.

<div class="p"><!----></div>
Three WSDL files are created by gSOAP: <tt>ns1.wsdl</tt>, <tt>ns2.wsdl</tt>, and
<tt>ns3.wsdl</tt>. Only the <tt>ns3.wsdl</tt> file is required to be published as it
contains the description of the combined service, while the others are
generated as a side-effect (and in case you want to develop these separate
services).

<div class="p"><!----></div>
	     <h3><a name="tth_sEc7.3">
7.3</a>&nbsp;&nbsp;<font color="#0000FF">Asynchronous One-Way Message Passing</font></h3><a name="sec:oneway1">
</a>

<div class="p"><!----></div>
SOAP RPC client-server interaction is synchronous: the client blocks until the server responds to the request.
gSOAP also supports asynchronous one-way message passing and the interoperable synchronous one-way message passing over HTTP. The two styles are similar, but only the latter is interoperable and is compliant to Basic Profile 1.0. The interoperable synchronous one-way message passing style over HTTP is discussed in Section&nbsp;<a href="#sec:oneway2">7.4</a> below.

<div class="p"><!----></div>
SOAP messaging routines are declared as function prototypes, just like service operations for SOAP RPC.  However, the output parameter is a
<i><b>void</b></i> type to indicate the absence of a return value.

<div class="p"><!----></div>
For example, the following header file specifies an event message for SOAP messaging:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__event(<b>int</b>&nbsp;eventNo, <b>void</b>);
</td></tr></table><br></i>
The gSOAP <i>soapcpp2</i> tool generates the following functions in <i>soapClient.cpp</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;soap_send_ns__event(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;URL, <b>const</b>&nbsp;<b>char</b>&nbsp;action, <b>int</b>&nbsp;event); <br />
<b>int</b>&nbsp;soap_recv_ns__event(<b>struct</b>&nbsp;soap *soap, <b>struct</b>&nbsp;ns__event *dummy); <br />
</td></tr></table><br></i>
The <i>soap_send_ns__event</i> function transmits the message to the destination URL by opening a socket and sending the SOAP encoded
message. The socket will remain
open after the send and has to be closed with <i>soap_closesock()</i>.  The open socket connection can also be used to obtain a service
response, e.g. with a <i>soap_recv</i> function call.

<div class="p"><!----></div>
The <i>soap_recv_ns__event</i> function waits for a SOAP message on the currently open socket (<i>soap.socket</i>) and fills the
<i><b>struct</b>&nbsp;ns__event</i> with the <i>ns__event</i> parameters (e.g. <i><b>int</b>&nbsp;eventNo</i>).
The <i><b>struct</b>&nbsp;ns__event</i> is automatically created by gSOAP and is a mirror image of the <i>ns__event</i> parameters:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__event <br />
{ <b>int</b>&nbsp;eventNo; <br />
}
</td></tr></table><br></i>
The gSOAP generated <i>soapServer.cpp</i> code includes a skeleton routine to accept the message.
(The skeleton routine does not respond with a SOAP response message.)
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;soap_serve_ns__event(<b>struct</b>&nbsp;soap *soap);
</td></tr></table><br></i>
The skeleton routine calls the user-implemented <i>ns__event(<b>struct</b>&nbsp;soap *soap, <b>int</b>&nbsp;eventNo)</i> routine (note the absence of the void
parameter!).

<div class="p"><!----></div>
As usual, the skeleton will be automatically called by the service operation request dispatcher that handles both the service operation
requests (RPCs) and messages:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ soap_serve(soap_new()); <br />
} <br />
<b>int</b>&nbsp;ns__event(<b>struct</b>&nbsp;soap *soap, <b>int</b>&nbsp;eventNo) <br />
{ <br />
&nbsp;&nbsp;&nbsp;... // handle event <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc7.4">
7.4</a>&nbsp;&nbsp;<font color="#0000FF">Implementing Synchronous One-Way Message Passing over HTTP</font></h3><a name="sec:oneway2">
</a>

<div class="p"><!----></div>
One-way SOAP message passing over HTTP as defined by the SOAP specification and
Basic Profile 1.0 is synchrounous, meaning that the server must respond with an
HTTP OK header (or HTTP 202 Accepted) and an empty body. To implement
synchrounous one-way messaging, the same setup for asynchrounous one-way
messaing discussed in Section&nbsp;<a href="#sec:oneway1">7.3</a> is used, but with one simple
addition at the client and server side for HTTP transfer.

<div class="p"><!----></div>
At the server side, we have to return an empty HTTP OK response. Normally with
one-way messaging the gSOAP engine closes the socket when the service operation
is finished, which is not desirable for synchronous one-way message exchanges
over HTTP: an HTTP response should be send. This is accomplished as follows.
For each one-way operation implemented in C/C++, we
replace the <i><b>return</b>&nbsp;SOAP_OK</i> with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__event(<b>struct</b>&nbsp;soap *soap, <b>int</b>&nbsp;eventNo) <br />
{ <br />
&nbsp;&nbsp;&nbsp;... // handle event <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_send_empty_response(soap, SOAP_OK); // SOAP_OK: return HTTP 202 ACCEPTED <br />
}
</td></tr></table><br></i>
At the client side, the empty response header must be parsed as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>if</b>&nbsp;(soap_send_ns__event(soap, eventNo) != SOAP_OK <br />
&nbsp;&nbsp;&nbsp;&#124;&#124; soap_recv_empty_response(soap) != SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(soap, stderr); <br />
...
</td></tr></table><br></i>
The synchronous (and asynchronous) one-way messaging supports HTTP keep-alive and chunking.

<div class="p"><!----></div>
Note: <i>soap_send_empty_response</i> returns the error code <i>SOAP_STOP</i>
to force the engine to stop producing a response message after the service
operation completed, which allows <i>soap_send_empty_response</i> to be used
with any service operation that should return HTTP 202.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc7.5">
7.5</a>&nbsp;&nbsp;<font color="#0000FF">How to Use the SOAP Serializers and Deserializers to Save and Load Application Data using XML Data Bindings</font></h3><a name="sec:bindings">
</a>

<div class="p"><!----></div>
The gSOAP XML databindings for C and C++ allow a seamless integration of XML in
C and C++ applications. Data can be serialized in XML and vice versa. WSDL and
XML schema files can be converted to C or C++ definitions. C and C++
definitions can be translated to WSDL and schemas to support legacy ANSI C
applications for example.

<div class="p"><!----></div>
	      <h4><a name="tth_sEc7.5.1">
7.5.1</a>&nbsp;&nbsp;<font color="#0000FF">Mapping XML Schema to C/C++ with wsdl2h</font></h4>

<div class="p"><!----></div>
Command:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h [options] XSD and WSDL files ...</i>
</td></tr></table><br></span>
The WSDL 1.1 and 2.0 standards are supported. If you have trouble
with WSDL 2.0 please contact the author. The entire XML schema 1.1 standard is
supported, except XPath expressions and assertions. This covers all of the
following schema components with their optional [ attributes ] shown:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xs:any [minOccurs, maxOccurs] &#62; <br />
  &lt;xs:anyAttribute&#62; <br />
  &lt;xs:all&#62; <br />
  &lt;xs:choice [minOccurs, maxOccurs] &#62; <br />
  &lt;xs:sequence [minOccurs, maxOccurs] &#62; <br />
  &lt;xs:group [name, ref] &#62; <br />
  &lt;xs:attributeGroup [name, ref] &#62; <br />
  &lt;xs:attribute [name, ref, type, use, default, fixed, form, wsdl:arrayType] &#62; <br />
  &lt;xs:element [name, ref, type, default, fixed, form, nillable, abstract, <br />
               substitutionGroup, minOccurs, maxOccurs] &#62; <br />
  &lt;xs:simpleType [name] &#62; <br />
  &lt;xs:complexType [name, abstract, mixed] &#62;
</td></tr></table><br></tt>
The supported facets are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xs:enumeration&#62; <br />
  &lt;xs:simpleContent&#62; <br />
  &lt;xs:complexContent&#62; <br />
  &lt;xs:list&#62; <br />
  &lt;xs:extension&#62; <br />
  &lt;xs:restriction&#62; <br />
  &lt;xs:length&#62; <br />
  &lt;xs:minLength&#62; <br />
  &lt;xs:maxLength&#62; <br />
  &lt;xs:minInclusive&#62; <br />
  &lt;xs:maxInclusive&#62; <br />
  &lt;xs:minExclusive&#62; <br />
  &lt;xs:maxExclusive&#62; <br />
  &lt;xs:precision&#62;	&nbsp;&nbsp;&nbsp;<span class="roman">maps to float/double with C formatted output</span> <br />
  &lt;xs:scale&#62;		&nbsp;&nbsp;&nbsp;<span class="roman">maps to float/double with C formatted output</span> <br />
  &lt;xs:totalDigits&#62;	&nbsp;&nbsp;&nbsp;<span class="roman">maps to float/double with C formatted output</span> <br />
  &lt;xs:fractionDigits&#62;	&nbsp;&nbsp;&nbsp;<span class="roman">maps to float/double with C formatted output</span> <br />
  &lt;xs:pattern&#62;		&nbsp;&nbsp;&nbsp;<span class="roman">content not automatically validated yet</span> <br />
  &lt;xs:union&#62;		&nbsp;&nbsp;&nbsp;<span class="roman">maps to string, content not validated yet</span>
</td></tr></table><br></tt>
  Other:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xs:import&#62; <br />
  &lt;xs:include&#62; <br />
  &lt;xs:redefine&#62; <br />
  &lt;xs:annotation&#62;
</td></tr></table><br></tt>
All primitive XSD types are supported (with the default mapping shown):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
xsd:string &nbsp;&nbsp;&nbsp;<span class="roman">maps to string (<b>char</b>*,<b>wchar_t</b>*,std::string,std::wstring)</span><br />
  xsd:boolean		&nbsp;&nbsp;&nbsp;<span class="roman">maps to bool (C++) or enum xsd__boolean (C)</span> <br />
  xsd:float		&nbsp;&nbsp;&nbsp;<span class="roman">maps to float</span> <br />
  xsd:double		&nbsp;&nbsp;&nbsp;<span class="roman">maps to double</span> <br />
  xsd:decimal		&nbsp;&nbsp;&nbsp;<span class="roman">maps to string, or use "#import "custom/decimal.h"</span> <br />
  xsd:precisionDecimal 	&nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span><br />
  xsd:duration		&nbsp;&nbsp;&nbsp;<span class="roman">maps to string, or use "#import "custom/duration.h"</span> <br />
  xsd:dateTime		&nbsp;&nbsp;&nbsp;<span class="roman">maps to time_t, or use "#import "custom/struct_tm.h"</span> <br />
  xsd:time		&nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:date		&nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:gYearMonth	&nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:gYear		&nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span>  <br />
  xsd:gMonth		&nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span>  <br />
  xsd:hexBinary		&nbsp;&nbsp;&nbsp;<span class="roman">maps to struct xsd__hexBinary</span> <br />
  xsd:base64Bianry 	&nbsp;&nbsp;&nbsp;<span class="roman">maps to struct xsd__base64Binary</span> <br />
  xsd:anyURI		&nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span>  <br />
  xsd:QName		&nbsp;&nbsp;&nbsp;<span class="roman">maps to _QName</span> (string normalization rules apply)<br />
  xsd:NOTATION		&nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span>
</td></tr></table><br></tt>
Note: string targets are defined in the <i>typemap.dat</i> file used by
<i>wsdl2h</i> to map XSD types. This allows the use of <i><b>char</b>*</i>,
<i><b>wsha_t*</b></i>, <i>std::string</i>, and <i>std::wstring</i> string types for
all XSD types mapped to strings.

<div class="p"><!----></div>
All non-primitive XSD types are supported (with the default mapping shown):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
xsd:normalizedString &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:token &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:language &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:IDREFS &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:ENTITIES &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:NMTOKEN &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:NMTOKENS &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:Name &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:NCName &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:ID &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:IDREF &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:ENTITY &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:integer &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span> <br />
  xsd:nonPositiveInteger &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span><br />
  xsd:negativeInteger &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span><br />
  xsd:long		&nbsp;&nbsp;&nbsp;<span class="roman">maps to LONG64</span> <br />
  xsd:int		&nbsp;&nbsp;&nbsp;<span class="roman">maps to int</span> <br />
  xsd:short		&nbsp;&nbsp;&nbsp;<span class="roman">maps to short</span> <br />
  xsd:byte		&nbsp;&nbsp;&nbsp;<span class="roman">maps to byte</span> <br />
  xsd:nonNegativeInteger &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span><br />
  xsd:unsignedLong	&nbsp;&nbsp;&nbsp;<span class="roman">maps to ULONG64</span> <br />
  xsd:unsignedInt	&nbsp;&nbsp;&nbsp;<span class="roman">maps to unsigned int</span> <br />
  xsd:unsignedShort	&nbsp;&nbsp;&nbsp;<span class="roman">maps to unsigned short</span> <br />
  xsd:unsignedByte	&nbsp;&nbsp;&nbsp;<span class="roman">maps to unsigned byte</span> <br />
  xsd:positiveInteger &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span><br />
  xsd:yearMonthDuration &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span><br />
  xsd:dayTimeDuration &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span><br />
  xsd:dateTimeStamp &nbsp;&nbsp;&nbsp;<span class="roman">maps to string</span>
</td></tr></table><br></tt>
There are several initialization flags to control XML serialization at runtime:

<ul>
<li> XML content validation is enforced with <i>SOAP_XML_STRICT</i>.
<div class="p"><!----></div>
</li>

<li> XML namespaces are supported, unless disabled with <i>SOAP_XML_IGNORENS</i>.
<div class="p"><!----></div>
</li>

<li> XML exclusive canonicalization is enabled with <i>SOAP_XML_CANONICAL</i>.
<div class="p"><!----></div>
</li>

<li> XML default <i>xmlns="..."</i> namespace bindings are used with <i>SOAP_XML_DEFAULTNS</i>.
<div class="p"><!----></div>
</li>

<li> XML is indented for enhanced readability with <i>SOAP_XML_INDENT</i>.
<div class="p"><!----></div>
</li>

<li> XML <i>xsi:nil</i> for NULL elements is serialized with <i>SOAP_XML_NIL</i>.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
To obtain C and/or C++ type definitions for XML schema components, run
<i>wsdl2h</i> on the schemas to generate a header file. This header file defines
the C/C++ type representations of the XML schema components. The header file
is then processed by the <i>soapcpp2</i> tool to generate
the serializers for these types. See Section&nbsp;<a href="#sec:mapping">1.4</a> for an overview to use <i>wsdl2h</i> and <i>soapcpp2</i> to map schemas to C/C++ types to obtain XML data bindings.

<div class="p"><!----></div>
	      <h4><a name="tth_sEc7.5.2">
7.5.2</a>&nbsp;&nbsp;<font color="#0000FF">Mapping C/C++ to XML Schema with soapcpp2</font></h4>

<div class="p"><!----></div>
To generate serialization code, execute:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 [options] header_file.h</i>
</td></tr></table><br></span>
The following C/C++ types are supported in the header file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>bool</b>&nbsp;<br />
  <b>enum</b>, <b>enum</b>* ('<b>enum</b>*' indicates serialized as a bitmask) <br />
  (<b>unsigned</b>) <b>char</b>, <b>short</b>, <b>int</b>, <b>long</b>, <b>long</b>&nbsp;<b>long</b>&nbsp;(also LONG64), <b>size_t</b> <br />
  <b>float</b>, <b>double</b>, <b>long</b><b>double</b>(#import "custom/long_double.h") <br />
  std::string, std::wstring, <b>char</b>[], <b>char</b>*, <b>wchar_t</b>* <br />
  _XML (a char* type to hold literal XML string content) <br />
  _QName (a char* type with normalized QName content of the form prefix:name) <br />
  <b>struct</b>, <b>class</b>&nbsp;(with single inheritance) <br />
  std::vector, std::list, std::deque, std::set (#import "import/stl.h") <br />
  <b>union</b>&nbsp;(requires preceding discriminant member field) <br />
  <b>typedef</b><br />
  <b>time_t</b> <br />
  <b>template</b> &lt;  &gt;  <b>class</b>(requires begin(), end(), size(), and insert() methods)  <br />
  <b>void</b>* (requires a preceding __type field to indicate the object pointed to) <br />
  <b>struct</b>&nbsp;xsd__hexBinary (special pre-defined type to hold binary content) <br />
  <b>struct</b>&nbsp;xsd__base64Binary (special pre-defined type to hold binary content) <br />
  <b>struct</b>&nbsp;tm (#import "custom/struct_tm.h") <br />
  <b>struct</b>&nbsp;timeval (#import "custom/struct_timeval.h") <br />
  pointers to any of the above (any pointer-linked structures are serializable, including cyclic graphs) <br />
  fixed-size arrays of all of the above
</td></tr></table><br></i>
Additional features and potential limitations:

<ul>
<li> A header file should not include any code statements, only data type declarations.
<div class="p"><!----></div>
</li>

<li> Nested classes and nested types are unnested.
<div class="p"><!----></div>
</li>

<li> Use <i>#import "file.h"</i> instead of <i>#include</i> to import other header files. The
  <i>#include</i> and <i>#define</i> directives are accepted, but deferred to the generated
  code.
<div class="p"><!----></div>
</li>

<li> C++ namespaces are supported (must cover entire header file content)
<div class="p"><!----></div>
</li>

<li> Optional DOM support can be used to store mixed content or literal XML
  content. Otherwise, mixed content may be lost. Use soapcpp2 option -d for DOM
  support.
<div class="p"><!----></div>
</li>

<li> Types are denoted transient using the '<b>extern</b>' qualifier, which prevents
  serialization as desired:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>extern</b> <b>class</b>&nbsp;name; // class 'name' is not serialized <br />
  <b>struct</b>&nbsp;name { <b>extern</b> <b>char</b>&nbsp;*name; <b>int</b>&nbsp;num; }; // 'name' is not serialized
</td></tr></table><br></i>
<div class="p"><!----></div>
</li>

<li> Only public members of a class can be serialized:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;name { <b>private</b>: <b>char</b>&nbsp;*secret; }; // 'secret' is not serialized
</td></tr></table><br></i>
<div class="p"><!----></div>
</li>

<li> Types are denoted "volatile", which means that they are declared elsewhere
  in the source code and should not be redeclared in the generated code nor augmented by the <i>soapcpp2</i> tool:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>volatile</b> <b>class</b>&nbsp;name { ... }; // defined here just to generate the serializers
</td></tr></table><br></i>
<div class="p"><!----></div>
</li>

<li> struct/class members are serialized as attributes when qualified with '@':
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;record { @<b>char</b>&nbsp;*name; <b>int</b>&nbsp;num; }; // attribute name, element num
</td></tr></table><br></i>
<div class="p"><!----></div>
</li>

<li> Strings with 8-bit content can hold ASCII (default) or UTF8. The latter is
  possible by enabling the <i>SOAP_C_UTFSTRING</i> flag. When enabled, all <i>std::string</i> and <i><b>char</b>*</i> strings MUST contain UTF8.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
The soapcpp2 tool generates serializers and deserializers
for all wsdl2h-generated or user-defined data structures that are specified in
the header file input to the compiler. The serializers and deserializers can be
found in the generated
<i>soapC.cpp</i> file. These serializers and deserializers can be used separately by an application without the need to build a
full client or service application.  This is useful for applications that need to save or export their data in XML or need to
import or load data stored in XML format.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.5.3">
7.5.3</a>&nbsp;&nbsp;<font color="#0000FF">Serializing C/C++ Data to XML</font></h4><a name="sec:serialize">
</a>

<div class="p"><!----></div>
We assume that the <i>wsdl2h</i> tool was used to map XML schema types to C/C++ data types. The <i>soapcpp2</i> tool then generates the (de)serializers for the C/C++ types. You can also use <i>soapcpp2</i> directly on a header file that declares annotated C/C++ data types to serialize.

<div class="p"><!----></div>
The following attributes can be set to control the destination and source for serialization and deserialization:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Variable</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap.socket</i> </td><td align="left">socket file descriptor for input and output (or set to <i>SOAP_INVALID_SOCKET</i>) </td></tr>
<tr><td align="left"><i>ostream *soap.os</i>	</td><td align="left">(C++ only) output stream used for send operations </td></tr>
<tr><td align="left"><i>istream *soap.is</i>	</td><td align="left">(C++ only) input stream used for receive operations </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap.sendfd</i> </td><td align="left">when <i>soap.socket</i>=<i>SOAP_INVALID_SOCKET</i>, this fd is used for send operations </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap.recvfd</i> </td><td align="left">when <i>soap.socket</i>=<i>SOAP_INVALID_SOCKET</i>, this fd is used for receive operations </td></tr></table>

</td></tr></table><br></span>
The following initializing and finalizing functions can be used:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;soap_begin_send(<b>struct</b>&nbsp;soap*)</i>	</td><td align="left">start a send/write phase </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap_end_send(<b>struct</b>&nbsp;soap*)</i> 	</td><td align="left">flush the buffer </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap_begin_recv(<b>struct</b>&nbsp;soap*)</i>	</td><td align="left">start a rec/read phase (if an HTTP header is present, parse it first) </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap_end_recv(<b>struct</b>&nbsp;soap*)</i> 	</td><td align="left">perform a id/href consistency check on deserialized data </td></tr></table>

</td></tr></table><br></span>
These operations do not open or close the connections. The application should open and close connections or files and set the <i>soap.socket</i>, <i>soap.os</i> or <i>soap.sendfd</i>, <i>soap.is</i> or <i>soap.recvfd</i> streams or descriptors.
When <i>soap.socket</i> &lt; 0 and none of the streams and descriptors are set, then the standard input and output will be used.

<div class="p"><!----></div>
The following options are available to control serialization:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap-&#62;encodingStyle = NULL; // to remove SOAP 1.1/1.2 encodingStyle<br />
soap_mode(soap, SOAP_XML_TREE); // XML without id-ref (no cycles!)<br />
soap_mode(soap, SOAP_XML_GRAPH); // XML with id-ref (including cycles)<br />
soap_set_namespaces(soap, <b>struct</b>&nbsp;Namespace *nsmap); //to set xmlns bindings
</td></tr></table><br></i>
See also Section&nbsp;<a href="#sec:flags">9.12</a> to control the I/O buffering and content encoding such as compression and DIME encoding.

<div class="p"><!----></div>
We assume that the <i>wsdl2h</i> tool was used to map XML schema types to C/C++ data types. The <i>soapcpp2</i> tool then generates the (de)serializers for the C/C++ types.

<div class="p"><!----></div>
To serialize data to an XML stream, two functions should be called to prepare
for serialization of the data and to send the data, respectively.  The first function,
<i>soap_serialize</i>, analyzes pointers and determines if multi-references
are required to encode the data and if cycles are present the object graph.
The second function, <i>soap_put</i>, produces the XML output on a stream.

<div class="p"><!----></div>
The <i>soap_serialize</i> and <i>soap_put</i> (and both combined by <i>soap_write</i>) functions are statically generated specific to a
data type. For example, <i>soap_serialize_float(&amp;soap, &amp;d)</i> is called to
serialize an <i><b>float</b></i> value and <i>soap_put_float(&amp;soap, &amp;d,
"number", NULL)</i> is called to output the floating point value in SOAP tagged
with the name <tt>&lt;number&#62;</tt>. The <i>soap_write_float(&amp;soap, &amp;d)</i> conveniently combines the initialization of output, writing the data, and finalizing the output.

<div class="p"><!----></div>
To initialize data, the <i>soap_default</i>
function of a data type can be used.  For example,
<i>soap_default_float(&amp;soap, &amp;d)</i> initializes the float to 0.0.  The
<i>soap_default</i> functions are useful to initialize complex data types such
as arrays, <i><b>struct</b></i>s, and <i><b>class</b></i> instances.  Note that the
<i>soap_default</i> functions do not need the gSOAP runtime context as a
first parameter.

<div class="p"><!----></div>
The following table lists the type naming conventions used by gSOAP:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Type</b></font> </td><td align="left"><font color="#FF0000"><b>Type Name</b></font> </td></tr>
<tr><td align="left"><i><b>char</b>*</i> </td><td align="left"><i>string</i> </td></tr>
<tr><td align="left"><i>wchar_t*</i> </td><td align="left"><i>wstring</i> </td></tr>
<tr><td align="left"><i><b>char</b></i> </td><td align="left"><i>byte</i> </td></tr>
<tr><td align="left"><i><b>bool</b></i> </td><td align="left"><i>bool</i> </td></tr>
<tr><td align="left"><i><b>double</b></i> </td><td align="left"><i>double</i> </td></tr>
<tr><td align="left"><i><b>int</b></i> </td><td align="left"><i>int</i> </td></tr>
<tr><td align="left"><i><b>float</b></i> </td><td align="left"><i>float</i> </td></tr>
<tr><td align="left"><i><b>long</b></i> </td><td align="left"><i>long</i> </td></tr>
<tr><td align="left"><i>LONG64</i> </td><td align="left"><i>LONG64</i> (Win32) </td></tr>
<tr><td align="left"><i><b>long</b>&nbsp;<b>long</b></i> </td><td align="left"><i>LONG64</i> (Unix/Linux) </td></tr>
<tr><td align="left"><i><b>short</b></i> </td><td align="left"><i>short</i> </td></tr>
<tr><td align="left"><i>time_t</i> </td><td align="left"><i>time</i> </td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>char</b></i> </td><td align="left"><i>unsignedByte</i> </td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>int</b></i> </td><td align="left"><i>unsignedInt</i> </td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>long</b></i> </td><td align="left"><i>unsignedLong</i> </td></tr>
<tr><td align="left"><i>ULONG64</i> </td><td align="left"><i>unsignedLONG64</i> (Win32)</td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>long</b>&nbsp;<b>long</b></i> </td><td align="left"><i>unsignedLONG64</i> (Unix/Linux) </td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>short</b></i> </td><td align="left"><i>unsignedShort</i> </td></tr>
<tr><td align="left"><i><u><span class="roman">T</span></u><span class="roman">[</span><u><span class="roman">N</span></u><span class="roman">]</span></i> </td><td align="left"><i>Array<u><span class="roman">N</span></u>Of<u><span class="roman">Type</span></u></i> where <u>Type</u> is the type name of <u>T</u> </td></tr>
<tr><td align="left"><i><u><span class="roman">T</span></u>*</i> </td><td align="left"><i>PointerTo<u><span class="roman">Type</span></u></i> where <u>Type</u> is the type name of <u>T</u> </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;Name</i> </td><td align="left"><i>Name</i> </td></tr>
<tr><td align="left"><i><b>class</b>&nbsp;Name</i> </td><td align="left"><i>Name</i> </td></tr>
<tr><td align="left"><i><b>enum</b>&nbsp;Name</i> </td><td align="left"><i>Name</i> </td></tr></table>

</td></tr></table><br></span>
Consider for example the following C code with a declaration of <i>p</i> as a
pointer to a <i><b>struct</b>&nbsp;ns__Person</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__Person { <b>char</b>&nbsp;*name; } *p;
</td></tr></table><br></i>
To serialize <i>p</i>, its address is passed to the function
<i>soap_serialize_PointerTons__Person</i> generated for this type by the
gSOAP <i>soapcpp2</i> compiler:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_serialize_PointerTons__Person(&amp;soap, &amp;p);
</td></tr></table><br></i>
The <b>address of</b> <i>p</i> is passed, so the serializer can determine whether
<i>p</i> was already serialized and to discover co-referenced objects and cycles in graph data structures that require SOAP encoding with id-ref serialization.
To generate the output, the address of <i>p</i> is passed to the function
<i>soap_put_PointerTons__Person</i> together with the name of an XML element
and an optional type string (to omit a type, use <i>NULL</i>):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_begin_send(&amp;soap); <br />
soap_put_PointerTons__Person(&amp;soap, &amp;p, "ns:element-name", "ns:type-name"); <br />
soap_end_send(&amp;soap);
</td></tr></table><br></i>
or the shorthand for the above (without the xsi type):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_write_PointerTons__Person(&amp;soap, &amp;p);
</td></tr></table><br></i>
This produces:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;ns:element-name xmlns:SOAP-ENV="..." xmlns:SOAP-ENC="..." xmlns:ns="..." <br />
&nbsp;&nbsp;&nbsp;... xsi:type="ns:type-name"&#62; <br />
&lt;name xsi:type="xsd:string"&#62;...&lt;/name&#62; <br />
&lt;/ns:element-name&#62;
</td></tr></table><br></tt>
The serializer is initialized with the <i>soap_begin_send(soap)</i> function
and closed with <i>soap_end_send(soap)</i>. All temporary data structures and
data structures deserialized on the heap are destroyed with the
<i>soap_destroy</i> and <i>soap_end</i> functions (in this order).

<div class="p"><!----></div>
The <i>soap_done</i> function should be used to reset the context, i.e.&nbsp;the last use of the context. To detach and deallocate the context, use <i>soap_free</i>.

<div class="p"><!----></div>
To remove the temporary data only and keep the deserialized data on the heap, use <i>soap_free_temp</i>.
Temporary data structures are only created if the encoded data uses pointers.
Each pointer in the encoded data has an internal hash table entry to determine
all multi-reference parts and cyclic parts of the complete data structure.

<div class="p"><!----></div>
You can assign an
output stream to <i>soap.os</i> or a file descriptor to <i>soap.sendfd</i>.
For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap.sendfd = open(file, O_RDWR | O_CREAT, S_IWUSR | S_IRUSR); <br />
soap_serialize_PointerTons__Person(&amp;soap, &amp;p); <br />
soap_begin_send(&amp;soap); <br />
soap_put_PointerTons__Person(&amp;soap, &amp;p, "ns:element-name", "ns:type-name"); <br />
soap_end_send(&amp;soap);
</td></tr></table><br></i>
The above can be abbreviated to
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap.sendfd = open(file, O_RDWR | O_CREAT, S_IWUSR | S_IRUSR); <br />
soap_write_PointerTons__Person(&amp;soap, &amp;p);
</td></tr></table><br></i>
The <i>soap_serialize</i> function is optional. It MUST be used when
the object graph contains cycles.
It MUST be called to preserve the logical coherence of pointer-based
data structures, where pointers may refer to co-referenced objects.
By calling <i>soap_serialize</i>, data structures shared through pointers are serialized only once and
referenced in XML using id-refs attributes.
The actual id-refs used depend on the SOAP encoding. To turn off SOAP encoding,
remove or avoid using the SOAP-ENV and SOAP-ENC namespace bindings in the namespace table.
In addition, the <i>SOAP_XML_TREE</i> and <i>SOAP_XML_GRAPH</i> flags can be used
to control the output by restricting serialization to XML trees or by enabling
multi-ref graph serialization with id-ref attribuation.

<div class="p"><!----></div>
To save the data as an XML tree (with one root) without any id-ref attributes, use the
<i>SOAP_XML_TREE</i> flag. The data structure MUST NOT contain pointer-based cycles.

<div class="p"><!----></div>
To preserve the exact structure of the data object graph and create XML with one root, use
the <i>SOAP_XML_GRAPH</i> output-mode flag (see
Section&nbsp;<a href="#sec:flags">9.12</a>). Use this flag and the <i>soap_serialize</i> function
to prepare the serialization of data with in-line id-ref attributes.
Using the <i>SOAP_XML_GRAPH</i> flag assures the preservation of the logical structure of the data

<div class="p"><!----></div>
For example, to encode the contents of two variables <i>var1</i> and <i>var2</i>
that may share data through pointer structures,
the serializers are called before the output routines:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<u><span class="roman">T1</span></u> var1; <br />
<u><span class="roman">T2</span></u> var2; <br />
<b>struct</b>&nbsp;soap soap; <br />
... <br />
soap_init(&amp;soap); // initialize <br />
<font size="+1"><span class="roman">[</span></font>soap_omode(&amp;soap, flags);<font size="+1"><span class="roman">]</span></font> // set output-mode flags (e.g. SOAP_ENC_XML<tt>|</tt>SOAP_ENC_ZLIB) <br />
soap_begin(&amp;soap); // start new (de)serialization phase <br />
soap_set_omode(&amp;soap, SOAP_XML_GRAPH); <br />
soap_serialize_<u><span class="roman">Type1</span></u>(&amp;soap, &amp;var1); <br />
soap_serialize_<u><span class="roman">Type2</span></u>(&amp;soap, &amp;var2); <br />
... <br />
<font size="+1"><span class="roman">[</span></font>soap.socket = a_socket_file_descriptor;<font size="+1"><span class="roman">]</span></font> // when using sockets <br />
<font size="+1"><span class="roman">[</span></font>soap.os = an_output_stream;<font size="+1"><span class="roman">]</span></font> // C++ <br />
<font size="+1"><span class="roman">[</span></font>soap.sendfd = an_output_file_descriptor;<font size="+1"><span class="roman">]</span></font> // C <br />
soap_begin_send(&amp;soap); <br />
soap_put_<u><span class="roman">Type1</span></u>(&amp;soap, &amp;var1, "<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>element-name1", "<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>type-name1"); <br />
soap_put_<u><span class="roman">Type2</span></u>(&amp;soap, &amp;var2, "<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>element-name2", "<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>type-name2"); <br />
... <br />
soap_end_send(&amp;soap); // flush <br />
soap_destroy(&amp;soap); // remove deserialized C++ objects <br />
soap_end(&amp;soap); // remove deserialized data structures <br />
soap_done(&amp;soap); // finalize last use of this context <br />
...
</td></tr></table><br></i>
where <u>Type1</u> is the type name of <u>T1</u> and
<u>Type2</u> is the type name of <u>T2</u> (see table above).  The
strings <i><font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>type-name1</i> and
<i><font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>type-name2</i> describe the schema types of the
elements.  Use <i>NULL</i> to omit this type information.

<div class="p"><!----></div>
For serializing class instances, method invocations MUST be used instead of function calls, for example
<i>obj.soap_serialize(&amp;soap)</i> and <i>obj.soap_put(&amp;soap, "elt", "type")</i>.  This ensures that the proper serializers are used for
serializing instances of derived classes.

<div class="p"><!----></div>
You can serialize a class instance to a stream as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
myClass obj; <br />
soap_init(&amp;soap); // initialize <br />
soap_begin(&amp;soap); // start new (de)serialization phase <br />
soap_set_omode(&amp;soap, SOAP_XML_GRAPH); <br />
obj.serialize(&amp;soap); <br />
soap.os = &amp;cout; // send to cout <br />
soap_begin_send(&amp;soap); <br />
obj.put(&amp;soap, "<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>element-name1", "<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>type-name1"); <br />
soap_end_send(&amp;soap); // flush <br />
... <br />
soap_destroy(&amp;soap); // remove deserialized C++ objects <br />
soap_end(&amp;soap); // remove deserialized data <br />
soap_done(&amp;soap); // finalize last use of this context
</td></tr></table><br></i>
When you declare a soap struct pointer as a data member in a class, you can overload the <tt>&lt;&lt;</tt> operator to serialize the class to streams:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
ostream &amp;operator<tt>&lt;&lt;</tt>(ostream &amp;o, <b>const</b>&nbsp;myClass &amp;e) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!e.soap) <br />
&nbsp;&nbsp;&nbsp;... error: need a soap struct to serialize (could use global struct) ... <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ostream *os = e.soap<tt>-&gt;</tt>os; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;e.soap<tt>-&gt;</tt>os = &amp;o; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_set_omode(e.soap, SOAP_XML_GRAPH);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;e.serialize(e.soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_begin_send(e.soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;e.put(e.soap, "myClass", NULL); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_end_send(e.soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;e.soap<tt>-&gt;</tt>os = os; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_clr_omode(e.soap, SOAP_XML_GRAPH); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;o; <br />
}
</td></tr></table><br></i>
Of course, when you construct an instance you must set its soap struct to a valid context.  Deserialized class instances with a soap struct data member will have their soap structs set automatically, see Section&nbsp;<a href="#sec:classmemory">9.13.2</a>.

<div class="p"><!----></div>
In principle, XML output for a data structure can be produced with <i>soap_put</i>
without calling the <i>soap_serialize</i> function first.
In this case, the result is similar to <i>SOAP_XML_TREE</i> which
means that no id-refs are output. Cycles in the data structure will crash the serialization
algorithm, even when the <i>SOAP_XML_GRAPH</i> is set.

<div class="p"><!----></div>
Consider the following <i><b>struct</b></i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "tricky.h": <br />
<b>struct</b>&nbsp;Tricky<br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;*p; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;n; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;*q; <br />
};
</td></tr></table><br></i>
The following fragment initializes the pointer fields <i>p</i> and <i>q</i> to the value of field <i>n</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
<b>struct</b>&nbsp;Tricky X; <br />
X.n = 1; <br />
X.p = &amp;X.n; <br />
X.q = &amp;X.n; <br />
soap_init(&amp;soap); <br />
soap_begin(&amp;soap); <br />
soap_serialize_Tricky(&amp;soap, &amp;X); <br />
soap_put_Tricky(&amp;soap, &amp;X, <tt>"Tricky"</tt>, NULL); <br />
soap_end(&amp;soap); // Clean up temporary data used by the serializer
</td></tr></table><br></i>
What is special about this data structure is that <i>n</i> is 'fixed' in the <i>Tricky</i> structure, and <i>p</i> and <i>q</i> both point to <i>n</i>. The gSOAP serializers strategically place the id-ref attributes such that <i>n</i> will be identified as the primary data source, while <i>p</i> and <i>q</i> are serialized with ref/href attributes.

<div class="p"><!----></div>
The resulting output is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;Tricky xsi:type="Tricky"&#62; <br />
&lt;p href="#2"/&#62;
&lt;n xsi:type="int"&#62;1&lt;/n&#62;
&lt;q href="#2"/&#62;
&lt;r xsi:type="int"&#62;2&lt;/r&#62;
&lt;/Tricky&#62;
&lt;id id="2" xsi:type="int"&#62;1&lt;/id&#62;
</td></tr></table><br></tt>
which uses an independent element at the end to represent the multi-referenced integer, assuming the <i>SOAP-ENV</i> and <i>SOAP-ENC</i> namespaces indicate SOAP 1.1 encoding.

<div class="p"><!----></div>
With the <i>SOAP_XML_GRAPH</i> flag the output is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;Tricky xsi:type="Tricky"&#62; <br />
&lt;p href="#2"/&#62;
&lt;n id="2" xsi:type="int"&#62;1&lt;/n&#62;
&lt;q href="#2"/&#62;
&lt;/Tricky&#62;
</td></tr></table><br></tt>
In this case, the XML is self-contained and multi-referenced data is accurately serialized.
The gSOAP generated deserializer for this data type will be able to accurately reconstruct the data from the XML (on the heap).

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.5.4">
7.5.4</a>&nbsp;&nbsp;<font color="#0000FF">Deserializing C/C++ Data from XML</font></h4><a name="sec:deserialize">
</a>

<div class="p"><!----></div>
We assume that the <i>wsdl2h</i> tool was used to map XML schema types to C/C++ data types. The <i>soapcpp2</i> tool then generates the (de)serializers for the C/C++ types. You can also use <i>soapcpp2</i> directly on a header file that declares annotated C/C++ data types to serialize.

<div class="p"><!----></div>
To deserialize a data type from XML, the <i>soap_get</i> (or the simpler <i>soap_read</i>) function for the data type to be deserialized is used. The outline of a program that deserializes two variables <i>var1</i> and <i>var2</i> is for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<u><span class="roman">T1</span></u> var1; <br />
<u><span class="roman">T2</span></u> var2; <br />
<b>struct</b>&nbsp;soap soap; <br />
... <br />
soap_init(&amp;soap); // initialize at least once <br />
<font size="+1"><span class="roman">[</span></font>soap_imode(&amp;soap, flags);<font size="+1"><span class="roman">]</span></font> // set input-mode flags <br />
soap_begin(&amp;soap); // begin new decoding phase <br />
<font size="+1"><span class="roman">[</span></font>soap.is = an_input_stream;<font size="+1"><span class="roman">]</span></font> // C++ <br />
<font size="+1"><span class="roman">[</span></font>soap.recvfd = an_input_file_desriptpr;<font size="+1"><span class="roman">]</span></font> // C <br />
soap_begin_recv(&amp;soap); // if HTTP/MIME/DIME/GZIP headers are present, parse them <br />
<b>if</b>&nbsp;(!soap_get_<u><span class="roman">Type1</span></u>(&amp;soap, &amp;var1, "<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>element-name1", "<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>type-name1")) <br />
&nbsp;&nbsp;&nbsp;... error ... <br />
<b>if</b>&nbsp;(!soap_get_<u><span class="roman">Type2</span></u>(&amp;soap, &amp;var2, "<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>element-name2", "<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>type-name1")) <br />
&nbsp;&nbsp;&nbsp;... error ... <br />
... <br />
soap_end_recv(&amp;soap); // check consistency of id/hrefs <br />
soap_destroy(&amp;soap); // remove deserialized C++ objects <br />
soap_end(&amp;soap); // remove deserialized data <br />
soap_done(&amp;soap); // finalize last use of the context
</td></tr></table><br></i>
The strings <i><font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>type-name1</i> and
<i><font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>type-name2</i> are the schema types of the elements
and should match the <tt>xsi:type</tt> attribute of the receiving message. To omit
the match, use <i>NULL</i> as the type.  For class instances, method invocation
can be used instead of a function call if the object is already instantiated,
i.e. <i>obj.soap_get(&amp;soap, "...", "...")</i>.

<div class="p"><!----></div>
The <i>soap_begin</i> call resets the deserializers. The <i>soap_destroy</i>
and <i>soap_end</i> calls remove the temporary data structures <b>and</b> the
decoded data that was placed on the heap.

<div class="p"><!----></div>
To remove temporary data while retaining the deserialized data on the heap, the
function <i>soap_free_temp</i> should be called instead of <i>soap_destroy</i> and
<i>soap_end</i>.

<div class="p"><!----></div>
One call to the <i>soap_get_Type</i> function of a type <i>Type</i> scans the
entire input to process its XML content and to capture SOAP 1.1 independent
elements (which contain multi-referenced objects). As a result, <i>soap.error</i> will set to <i>SOAP_EOF</i>.
Also storing
multiple objects into one file will fail to decode them properly with multiple <i>soap_get</i> calls. A well-formed XML document should
only have one root anyway, so don't save multiple objects into one file. If you
must save multiple objects, create a linked list or an array of objects and save
the linked list or array. You could use the <i>soap_in_Type</i> function instead of the <i>soap_get_Type</i> function. The <i>soap_in_Type</i> function parses one XML element at a time.

<div class="p"><!----></div>
You can deserialize class instances from a stream as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
myClass obj; <br />
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); // initialize <br />
soap.is = &amp;cin; // read from cin <br />
soap_begin_recv(&amp;soap); // if HTTP header is present, parse it <br />
<b>if</b>&nbsp;(soap_get_myClass(&amp;soap, &amp;obj, "myClass", NULL) == NULL) <br />
&nbsp;&nbsp;&nbsp;... error ... <br />
soap_end_recv(&amp;soap); // check consistency of id/hrefs <br />
... <br />
soap_destroy(&amp;soap); // remove deserialized C++ objects <br />
soap_end(&amp;soap); // remove deserialized data <br />
soap_done(&amp;soap); // finalize last use of the context
</td></tr></table><br></i>
This can be abbreviated to:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
myClass obj; <br />
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); // initialize <br />
soap.is = &amp;cin; // read from cin <br />
<b>if</b>&nbsp;(soap_read_myClass(&amp;soap, &amp;obj, NULL) != SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;... error ... <br />
... <br />
soap_destroy(&amp;soap); // remove deserialized C++ objects <br />
soap_end(&amp;soap); // remove deserialized data <br />
soap_done(&amp;soap); // finalize last use of the context
</td></tr></table><br></i>
When declaring a soap struct pointer as a data member in a class, you can overload the <tt>&gt;&gt;</tt> operator to parse and deserialize a class instance from a stream:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
istream &amp;operator<tt>&gt;&gt;</tt>(istream &amp;i, myClass &amp;e) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!e.soap) <br />
&nbsp;&nbsp;&nbsp;... error: need soap struct to deserialize (could use global struct)... <br />
&nbsp;&nbsp;&nbsp;istream *is = e.soap<tt>-&gt;</tt>is; <br />
&nbsp;&nbsp;&nbsp;e.soap<tt>-&gt;</tt>is = &amp;i; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_read_myClass(e.soap, &amp;e) != SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... error ... <br />
&nbsp;&nbsp;&nbsp;e.soap<tt>-&gt;</tt>is = is; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;i; <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.5.5">
7.5.5</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4><a name="sec:example9">
</a>

<div class="p"><!----></div>
As an example, consider the following data type declarations:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "person.h": <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__Name; <br />
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>int</b>&nbsp;xsd__unsignedInt; <br />
<b>enum</b>&nbsp;ns__Gender {male, female}; <br />
<b>class</b>&nbsp;ns__Address <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;xsd__string street; <br />
&nbsp;&nbsp;&nbsp;xsd__unsignedInt number; <br />
&nbsp;&nbsp;&nbsp;xsd__string city; <br />
}; <br />
<b>class</b>&nbsp;ns__Person <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;xsd__Name name; <br />
&nbsp;&nbsp;&nbsp;<b>enum</b>&nbsp;ns__Gender gender; <br />
&nbsp;&nbsp;&nbsp;ns__Address address; <br />
&nbsp;&nbsp;&nbsp;ns__Person *mother; <br />
&nbsp;&nbsp;&nbsp;ns__Person *father; <br />
};
</td></tr></table><br></i>
The following program uses these data types to write to standard output a data structure that contains the data of a person named "John" living at Downing st. 10 in Londen. He has a mother
"Mary" and a father "Stuart". After initialization, the class instance for "John" is serialized and encoded in XML to the
standard output stream using gzip compression (requires the Zlib library, compile sources with -DWITH_GZIP):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "person.cpp": <br />
#include "soapH.h" <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;ns__Person mother, father, john; <br />
&nbsp;&nbsp;&nbsp;mother.name = <tt>"Mary"</tt>; <br />
&nbsp;&nbsp;&nbsp;mother.gender = female; <br />
&nbsp;&nbsp;&nbsp;mother.address.street = <tt>"Downing&nbsp;st."</tt>; <br />
&nbsp;&nbsp;&nbsp;mother.address.number = 10; <br />
&nbsp;&nbsp;&nbsp;mother.address.city = <tt>"London"</tt>; <br />
&nbsp;&nbsp;&nbsp;mother.mother = NULL; <br />
&nbsp;&nbsp;&nbsp;mother.father = NULL; <br />
&nbsp;&nbsp;&nbsp;father.name = <tt>"Stuart"</tt>; <br />
&nbsp;&nbsp;&nbsp;father.gender = male; <br />
&nbsp;&nbsp;&nbsp;father.address.street = <tt>"Main&nbsp;st."</tt>; <br />
&nbsp;&nbsp;&nbsp;father.address.number = 5; <br />
&nbsp;&nbsp;&nbsp;father.address.city = <tt>"London"</tt>; <br />
&nbsp;&nbsp;&nbsp;father.mother = NULL; <br />
&nbsp;&nbsp;&nbsp;father.father = NULL; <br />
&nbsp;&nbsp;&nbsp;john.name = <tt>"John"</tt>; <br />
&nbsp;&nbsp;&nbsp;john.gender = male; <br />
&nbsp;&nbsp;&nbsp;john.address = mother.address; <br />
&nbsp;&nbsp;&nbsp;john.mother = &amp;mother; <br />
&nbsp;&nbsp;&nbsp;john.father = &amp;father; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_omode(&amp;soap, SOAP_ENC_ZLIB | SOAP_XML_GRAPH); // see&nbsp;<a href="#sec:flags">9.12</a> <br />
&nbsp;&nbsp;&nbsp;soap_begin(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_begin_send(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;john.soap_serialize(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;john.soap_put(&amp;soap, <tt>"johnnie"</tt>, NULL); <br />
&nbsp;&nbsp;&nbsp;soap_end_send(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_destroy(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); <br />
} <br />
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{ <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC","http://schemas.xmlsoap.org/soap/encoding/"}, <br />
&nbsp;&nbsp;&nbsp;{"xsi", "http://www.w3.org/2001/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd", "http://www.w3.org/2001/XMLSchema"}, <br />
&nbsp;&nbsp;&nbsp;{"ns", "urn:person"}, // Namespace URI of the "Person" data type <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} <br />
};
</td></tr></table><br></i>
The header file is processed and the application compiled on Linux/Unix with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 person.h</i> <br />
<i> &gt;  c++ -DWITH_GZIP -o person person.cpp soapC.cpp stdsoap2.cpp -lsocket -lxnet -lnsl -lz</i>
</td></tr></table><br></span>
(Depending on your system configuration, the libraries <i>libsocket.a</i>,
<i>libxnet.a</i>, <i>libnsl.a</i>
are required. Compiling on Linux typically does not require the inclusion of those
libraries.)
See&nbsp;<a href="#sec:compression">19.27</a> for details on compression with gSOAP.

<div class="p"><!----></div>
Running the <i>person</i> application results in the compressed XML output:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;johnnie xsi:type="ns:Person" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsd="http://www.w3.org/2001/XMLSchema" <br />
&nbsp;&nbsp;&nbsp;xmlns:ns="urn:person" <br />
&nbsp;&nbsp;&nbsp;SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&#62; <br />
&lt;name xsi:type="xsd:Name"&#62;John&lt;/name&#62; <br />
&lt;gender xsi:type="ns:Gender"&#62;male&lt;/gender&#62; <br />
&lt;address xsi:type="ns:Address"&#62; <br />
&lt;street id="3" xsi:type="xsd:string"&#62;Dowling st.&lt;/street&#62; <br />
&lt;number xsi:type="unsignedInt"&#62;10&lt;/number&#62; <br />
&lt;city id="4" xsi:type="xsd:string"&#62;London&lt;/city&#62; <br />
&lt;/address&#62; <br />
&lt;mother xsi:type="ns:Person"&#62; <br />
&lt;name xsi:type="xsd:Name"&#62;Mary&lt;/name&#62; <br />
&lt;gender xsi:type="ns:Gender"&#62;female&lt;/gender&#62; <br />
&lt;address xsi:type="ns:Address"&#62; <br />
&lt;street href="#3"/&#62; <br />
&lt;number xsi:type="unsignedInt"&#62;5&lt;/number&#62; <br />
&lt;city href="#4"/&#62; <br />
&lt;/address&#62; <br />
&lt;/mother&#62; <br />
&lt;father xsi:type="ns:Person"&#62; <br />
&lt;name xsi:type="xsd:Name"&#62;Stuart&lt;/name&#62; <br />
&lt;gender xsi:type="ns:Gender"&#62;male&lt;/gender&#62; <br />
&lt;address xsi:type="ns:Address"&#62; <br />
&lt;street xsi:type="xsd:string"&#62;Main st.&lt;/street&#62; <br />
&lt;number xsi:type="unsignedInt"&#62;13&lt;/number&#62; <br />
&lt;city href="#4"/&#62; <br />
&lt;/address&#62; <br />
&lt;/father&#62; <br />
&lt;/johnnie&#62;
</td></tr></table><br></tt>
The following program fragment decodes this content from standard input and reconstructs the original data structure on the heap:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;ns__Person *mother, *father, *john = NULL; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_imode(&amp;soap, SOAP_ENC_ZLIB); // optional: gzip is detected automatically <br />
&nbsp;&nbsp;&nbsp;soap_begin(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;((john = soap_get_ns__Person(&amp;soap, NULL, NULL, NULL)) == NULL) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... error ... <br />
&nbsp;&nbsp;&nbsp;mother = john<tt>-&gt;</tt>mother; <br />
&nbsp;&nbsp;&nbsp;father = john<tt>-&gt;</tt>father; <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_end_recv(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_free_temp(&amp;soap); // Clean up temporary data but keep deserialized data <br />
} <br />
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{ <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC","http://schemas.xmlsoap.org/soap/encoding/"}, <br />
&nbsp;&nbsp;&nbsp;{"xsi", "http://www.w3.org/2001/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd", "http://www.w3.org/2001/XMLSchema"}, <br />
&nbsp;&nbsp;&nbsp;{"ns", "urn:person"}, // Namespace URI of the "Person" data type <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} <br />
};
</td></tr></table><br></i>
It is REQUIRED to either pass <i>NULL</i> to the <i>soap_get</i> routine, or a valid pointer to a data structure that can
hold the decoded content. If the data <i>john</i> was already allocated then it does not need to be allocated again as the following demonstrates.
The following program fragment decodes the SOAP content in a <i><b>struct</b>&nbsp;ns__Person</i> allocated on the stack:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
<b>int</b>&nbsp;main() <br />
{<br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;ns__Person *mother, *father, john; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_default_ns__Person(&amp;soap, &amp;john); <br />
&nbsp;&nbsp;&nbsp;soap_imode(&amp;soap, SOAP_ENC_ZLIB); // optional <br />
&nbsp;&nbsp;&nbsp;soap_begin(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_begin_recv(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_get_ns__Person(&amp;soap, &amp;john, "johnnie", NULL) == NULL) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... error ... <br />
&nbsp;&nbsp;&nbsp;... <br />
} <br />
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
&nbsp;&nbsp;&nbsp;...
</td></tr></table><br></i>
Note the use of <i>soap_default_ns__Person</i>. This routine is generated by the gSOAP <i>soapcpp2</i> tool and assigns default
values to the fields of <i>john</i>.

<div class="p"><!----></div>
	      <h4><a name="tth_sEc7.5.6">
7.5.6</a>&nbsp;&nbsp;<font color="#0000FF">Serializing and Deserializing Class Instances to Streams</font></h4>

<div class="p"><!----></div>
C++ applications can define appropriate stream operations on objects for (de)serialization of objects on streams.
This is best illustrated with an example. Section&nbsp;<a href="#sec:serialize">7.5.3</a> gives details on serializing types in general.
Consider the class
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;ns__person <br />
{ <b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap *soap; // we need this, see below <br />
&nbsp;&nbsp;&nbsp;ns__person(); <br />
&nbsp;&nbsp;&nbsp;~ns__person(); <br />
};
</td></tr></table><br></i>
The <i><b>struct</b>&nbsp;soap</i> member is used to bind the instances to a gSOAP
context for (de)serialization.  We use the gSOAP <i>soapcpp2</i> compiler from the command
prompt to generate the class (de)serializers (assuming that <i>person.h</i>
contains the class declaration):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 person.h</i>
</td></tr></table><br></span>
gSOAP generates the (de)serializers and an instantiation function for the class
<i>soap_new_ns__person(<b>struct</b>&nbsp;soap *soap, <b>int</b>&nbsp;num)</i> to instantiate
one or more objects and associate them with a gSOAP context for deallocation with <i>soap_destroy(soap)</i>.  To instantiate a single object, omit
the <i>num</i> parameter or set to -1. To instantiate an array of objects, set <i>num</i> &#8805; 0.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
#include "ns.nsmap" <br />
... <br />
<b>struct</b>&nbsp;soap *soap = soap_new(); <br />
ns__person *p = soap_new_ns__person(soap); <br />
... <br />
cout  &lt;&lt;  p; // serialize p in XML <br />
... <br />
in  &gt;&gt;  p; // parse XML and deserialize p <br />
... <br />
soap_destroy(soap); // deletes p too <br />
soap_end(soap); <br />
soap_done(soap);
</td></tr></table><br></i>
The stream operations are implemented as follows
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
ostream &amp;<b>operator</b><tt>&lt;&lt;</tt>(ostream &amp;o, <b>const</b>&nbsp;ns__person &amp;p) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!p.soap) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;o; // need a gSOAP context to serialize <br />
&nbsp;&nbsp;&nbsp;p.soap<tt>-&gt;</tt>os = &amp;o; <br />
&nbsp;&nbsp;&nbsp;soap_omode(p.soap, SOAP_XML_TREE); // XML tree or graph <br />
&nbsp;&nbsp;&nbsp;p.soap_serialize(p.soap); <br />
&nbsp;&nbsp;&nbsp;soap_begin_send(p.soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(p.soap_put(p.soap, "person", NULL) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |  |  soap_end_send(p.soap)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;; // handle I/O error <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;o; <br />
} <br />
istream &amp;<b>operator</b><tt>&gt;&gt;</tt>(istream &amp;i, ns__person &amp;p) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!p.soap) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;o; // need a gSOAP context to parse XML and deserialize <br />
&nbsp;&nbsp;&nbsp;p.soap<tt>-&gt;</tt>is = &amp;i; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_begin_recv(p.soap) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |  |  p.soap_in(p.soap, NULL, NULL) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |  |  soap_end_recv(p.soap)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;; // handle I/O error <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;i; <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc7.5.7">
7.5.7</a>&nbsp;&nbsp;<font color="#0000FF">How to Specify Default Values for Omitted Data</font></h4><a name="sec:default">
</a>

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> compiler generates <i>soap_default</i> functions for all data types.  The default values of the primitive types can be
easily changed by defining any of the following macros in the <i>stdsoap2.h</i> file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#define SOAP_DEFAULT_bool <br />
#define SOAP_DEFAULT_byte <br />
#define SOAP_DEFAULT_double <br />
#define SOAP_DEFAULT_float <br />
#define SOAP_DEFAULT_int <br />
#define SOAP_DEFAULT_long <br />
#define SOAP_DEFAULT_LONG64 <br />
#define SOAP_DEFAULT_short <br />
#define SOAP_DEFAULT_string <br />
#define SOAP_DEFAULT_time <br />
#define SOAP_DEFAULT_unsignedByte <br />
#define SOAP_DEFAULT_unsignedInt <br />
#define SOAP_DEFAULT_unsignedLong <br />
#define SOAP_DEFAULT_unsignedLONG64 <br />
#define SOAP_DEFAULT_unsignedShort <br />
#define SOAP_DEFAULT_wstring
</td></tr></table><br></i>
Instead of adding these to <i>stdsoap2.h</i>, you can also compile with option <i>-DWITH_SOAPDEFS_H</i> and include your
definitions in file <i>userdefs.h</i>.
The absence of a data value in a receiving SOAP message will result in the assignment of a default value to a primitive type upon
deserialization.

<div class="p"><!----></div>
Default values can also be assigned to individual <i><b>struct</b></i> and <i><b>class</b></i> fields of primitive type. For example,
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;MyRecord <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name = "Unknown"; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;value = 9999; <br />
&nbsp;&nbsp;&nbsp;<b>enum</b>&nbsp;Status { active, passive } status = passive; <br />
}
</td></tr></table><br></i>
Default values are assigned to the fields on receiving a SOAP/XML message in which the data values are absent.

<div class="p"><!----></div>
Because method requests and responses are essentially structs, default values can also be assigned to method parameters. The
default parameter values do not control the parameterization of C/C++ function calls, i.e. all actual parameters must be present
when calling a function. The default parameter values are used in case an inbound request or response message lacks the XML
elements with parameter values. For example, a Web service can use default values to fill-in absent parameters in a
SOAP/XML request:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__login(<b>char</b>&nbsp;*uid = "anonymous", <b>char</b>&nbsp;*pwd = "guest", <b>bool</b>&nbsp;granted);
</td></tr></table><br></i>
When the request message lacks uid and pwd parameters, e.g.:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;?xml version="1.0" encoding="UTF-8"?&#62; <br />
&lt;SOAP-ENV:Envelope <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsd="http://www.w3.org/2001/XMLSchema" <br />
&nbsp;&nbsp;&nbsp;xmlns:ns="http://tempuri.org"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;SOAP-ENV:Body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;ns:login&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/ns:login&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/SOAP-ENV:Body&#62; <br />
&lt;/SOAP-ENV:Envelope&#62;
</td></tr></table><br></tt>
then the service uses the default values.
In addition, the default values will show up in the SOAP/XML request and response message examples generated by the gSOAP
compiler.

<div class="p"><!----></div>
 <h2><a name="tth_sEc8">
8</a>&nbsp;&nbsp;<font color="#0000FF">The wsdl2h WSDL and Schema Importer</font></h2><a name="sec:wsdlin">
</a>

<div class="p"><!----></div>
The <i>wsdl2h</i> tool is an advanced application that converts one or more
WSDLs to C/C++. It can also be used without WSDLs to convert XML schemas (XSD
files) to C/C++ to implement XML data bindings in C and C++.

<div class="p"><!----></div>
The creation of C and C++ applications from one of more WSDL service
descriptions is a two-step process.

<div class="p"><!----></div>
To convert a WSDL to C++, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h <u><span class="roman">file</span></u>.wsdl</i>
</td></tr></table><br></span>
to generate a C++ header file <i><u><span class="roman">file</span></u>.h</i>.
This generated header file is a Web service specification that contains the parameter types and service function definitions in an understandable format in C++ (or ANSI C as shown below).
Web service operations are represented as function prototypes. Schema types are
represented by semantically equivalent C/C++ types that are convenient and
natural to use in a C/C++ application. The generated header file also contains
various annotations related to the Web service properties defined in the WSDL.

<div class="p"><!----></div>
To generate ANSI C, use option <i>-c</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h -c <u><span class="roman">file</span></u>.wsdl</i>
</td></tr></table><br></span>
Multiple WSDL specifications can be processed at once and saved to one file with the <i>-o</i> option:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h -o file.h file1.wsdl file2.wsdl file3.wsdl</i>
</td></tr></table><br></span>
You can retrieve WSDLs from one of more URLs:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h -o file.h http://www.example.com/example.wsdl</i>
</td></tr></table><br></span>
To convert XML schemas to C or C++ XML data binding code, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  wsdl2h -o file.h file1.xsd file2.xsd file3.xsd</i>
</td></tr></table><br></span>
The <i>wsdl2h</i>-generated header file <i>file.h</i> is processed by the
<i>soapcpp2</i> tool to auto-generate the advanced data binding logic to
convert the C/C++ data to XML and vice versa at runtime for your SOAP/XML
application.

<div class="p"><!----></div>
To process a gSOAP header file <i>file.h</i> (generated by <i>wsdl2h</i>) to generate advanced XML data bindings for C++, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -i -Iimport file.h</i>
</td></tr></table><br></span>
When the header file <i>file.h</i> was generated for C++, then this command
generates a couple of C++ source files (more details will follow in
Section&nbsp;<a href="#sec:soapcpp2">9</a>) that implement XML encoders for the data binding.
Option <i>-i</i> generates a client proxy objects and service objects to invoke
and serve SOAP/XML operations, respectively. Option <i>-Iimport</i> sets the
import directory for imported files from the package's <i>import</i>, such as
<i>stlvector.h</i> for STL vector serialization support.

<div class="p"><!----></div>
When the header file <i>file.h</i> was generated for ANSI C, then the above
command generates a couple of C files that implement XML encoders, client stubs
for remote invocation, and service skeletons for service operations. 

<div class="p"><!----></div>
Consider for example the following commands to implement a c++ client of a service:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
 &gt;  wsdl2h -o calc.h http://www.genivia.com/calc.wsdl <br />
... <br />
 &gt;  soapcpp2 -i -Iimport calc.h
</td></tr></table><br></span>
The first command generates <i>calc.h</i> from the WSDL at the specified URL.
The header file is then processed by the <i>soapcpp2</i> tool to generate the
proxies (and service objects that we will not use) for the client application.

<div class="p"><!----></div>
The C++ client application uses the auto-generated <i>soapcalcProxy.h</i> class and
<i>calc.nsmap</i> XML namespace table to access the Web
service. Both need to be <i>#include</i>-d in your source. Then compile and link
the <i>soapcalcProxy.cpp</i>, <i>soapC.cpp</i> and <i>stdsoap2.cpp</i> sources to complete the build.

<div class="p"><!----></div>
     <h3><a name="tth_sEc8.1">
8.1</a>&nbsp;&nbsp;<font color="#0000FF">wsdl2h Options</font></h3>

<div class="p"><!----></div>
The <i>wsdl2h</i> tool is an advanced XML data binding tool for converting WSDLs
and XML schemas (XSD files) to C or C++. The tool takes WSDL and/or XSD files
or URLs and converts these to a C or C++ specification in one easy-to-read
C/C++ header file. <b>The header file is not intended to be included in your
code directly!</b>. It should be converted by <i>soapcpp2</i> to generate the logic
for the data bindings. It can however be safely converted by a documentation
tool such as Doxygen to analyze and represent the service operations and data
in a convenient layout. To this end, the header file is self-explanatory.

<div class="p"><!----></div>
The <i>wsdl2h</i> tool generates only one file, the header file that includes
all of the information obtained from all WSDL and schema files provided to the
tool at the command-line prompt. The default output file name of <i>wsdl2h</i>
is the first WSDL/schema input file name but with extension <i>.h</i> instead of
<i>.wsdl</i> (or <i>.xsd</i>). When an input file is absent or a WSDL file from a
Web location is accessed, the header output will be produced on the standard
output unless option <i>-o</i> is used to direct the output to a file.

<div class="p"><!----></div>
The <i>wsdl2h</i> command-line options are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Option</b></font>	</td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>-a</i>	</td><td align="left">generate indexed struct names for local elements with anonymous types </td></tr>
<tr><td align="left"><i>-b</i>	</td><td align="left">bi-directional operations to serve one-way response messages (duplex)</td></tr>
<tr><td align="left"><i>-c</i>	</td><td align="left">generate C source code </td></tr>
<tr><td align="left"><i>-d</i>	</td><td align="left">use DOM to populate xs:any and xsd:anyType elements </td></tr>
<tr><td align="left"><i>-e</i>	</td><td align="left">don't qualify enum names </td></tr>
<tr><td align="left"></td><td align="left">This option is for backward compatibility with gSOAP 2.4.1 and earlier. </td></tr>
<tr><td align="left"></td><td align="left">The option does not produce code that conforms to WS-I Basic Profile 1.0a. </td></tr>
<tr><td align="left"><i>-f</i>      </td><td align="left">generate flat C++ class hierarchy for schema extensions </td></tr>
<tr><td align="left"><i>-g</i>	</td><td align="left">generate global top-level element declarations </td></tr>
<tr><td align="left"><i>-h</i>      </td><td align="left">print help information </td></tr>
<tr><td align="left"><i>-I path</i>	</td><td align="left">use path to locate source files for <i>#import</i> </td></tr>
<tr><td align="left"><i>-i</i>      </td><td align="left">don't import (advanced option)</td></tr>
<tr><td align="left"><i>-j</i>	</td><td align="left">don't generate <i>SOAP_ENV__Header</i> and <i>SOAP_ENV__Detail</i> definitions </td></tr>
<tr><td align="left"><i>-k</i>	</td><td align="left">don't generate <i>SOAP_ENV__Header</i> <i>mustUnderstand</i> qualifiers </td></tr>
<tr><td align="left"><i>-l</i>	</td><td align="left">include license information in output </td></tr>
<tr><td align="left"><i>-m</i>	</td><td align="left">use xsd.h module to import primitive types </td></tr>
<tr><td align="left"><i>-N name</i>	</td><td align="left">use <i>name</i> for service prefixes to produce a service for each binding </td></tr>
<tr><td align="left"><i>-n name</i>	</td><td align="left">use <i>name</i> as the base namespace prefix name instead of <i>ns</i> </td></tr>
<tr><td align="left"><i>-o file</i>  </td><td align="left">output to file </td></tr>
<tr><td align="left"><i>-P</i>      </td><td align="left">don't create polymorphic types inherited from <i>xsd__anyType</i> </td></tr>
<tr><td align="left"><i>-p</i>      </td><td align="left">create polymorphic types inherited from base <i>xsd__anyType</i> </td></tr>
<tr><td align="left"></td><td align="left">This is automatically performed when WSDL contains polymorphic definitions </td></tr>
<tr><td align="left"><i>-q name</i>	</td><td align="left">use <i>name</i> for the C++ namespace of all declarations </td></tr>
<tr><td align="left"><i>-r host[:port[:uid:pwd]]</i>      </td><td align="left">connect via proxy host, port, and proxy credentials </td></tr>
<tr><td align="left"><i>-r:uid:pwd</i>      </td><td align="left">connect with authentication credentials (digest auth requires SSL) </td></tr>
<tr><td align="left"><i>-R</i>      </td><td align="left">generate REST operations for REST bindings in the WSDL </td></tr>
<tr><td align="left"><i>-s</i>      </td><td align="left">don't generate STL code (no std::string and no std::vector) </td></tr>
<tr><td align="left"><i>-t file</i>  </td><td align="left">use type map file instead of the default file typemap.dat </td></tr>
<tr><td align="left"><i>-u</i>	</td><td align="left">don't generate unions </td></tr>
<tr><td align="left"><i>-v</i>      </td><td align="left">verbose output </td></tr>
<tr><td align="left"><i>-W</i>	</td><td align="left">suppress warnings </td></tr>
<tr><td align="left"><i>-w</i>      </td><td align="left">always wrap response parameters in a response struct </td></tr>
<tr><td align="left"><i>-x</i>	</td><td align="left">don't generate <i>_XML any/anyAttribute</i> extensibility elements </td></tr>
<tr><td align="left"><i>-y</i>	</td><td align="left">generate typedef synonyms for structs and enums </td></tr>
<tr><td align="left"><i>-z1</i>     </td><td align="left">compatibility with 2.7.6e: generate pointer-based arrays</td></tr>
<tr><td align="left"><i>-z2</i>	</td><td align="left">compatibility with 2.7.15: qualify element/attribute referenced members</td></tr>
<tr><td align="left"><i>-z3</i>     </td><td align="left">compatibility with 2.7.16 to 2.8.7: qualify element/attribute references</td></tr>
<tr><td align="left"><i>-z4</i>     </td><td align="left">compatibility up to 2.8.11: don't generate union structs in std::vector </td></tr>
<tr><td align="left"><i>-z5</i>     </td><td align="left">compatibility up to 2.8.15 </td></tr>
<tr><td align="left"><i>-z5</i>     </td><td align="left">compatibility up to 2.8.17 </td></tr>
<tr><td align="left"><i>-_</i>	</td><td align="left">don't generate <i>_USCORE</i> (replace with UNICODE _x005f) </td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
Note: see <i>README.txt</i> in the <i>wsdl</i> directory for the latest
information on installation and options to of the <i>wsdl2h</i> WSDL/schema importer.

<div class="p"><!----></div>
     <h3><a name="tth_sEc8.2">
8.2</a>&nbsp;&nbsp;<font color="#0000FF">Customizing Data Bindings With The typemap.dat File</font></h3><a name="sec:typemap">
</a>

<div class="p"><!----></div>
The <i>typemap.dat</i> file for the <i>wsdl2h</i> tool is intended to customize or optimize
the type bindings by mapping schema types to C/C++ types.  It contains custom
XML Schema to C/C++ type bindings and a few bindings are defined for
convenience.

<div class="p"><!----></div>
Here is an example typemap file's content:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
#       This file contains custom definitions of the XML Schema types and <br />
#       C/C++ types for your project, and XML namespace prefix definitions. <br />
#       The wsdl2h WSDL importer consults this file to determine bindings. <br />
  <br />
<tt>[</tt> <br />
// This comment will be included in the generated .h file <br />
// You can include any additional declarations, includes, imports, etc. <br />
// within <tt>[</tt> <tt>]</tt> sections. The brackets MUST appear at the start of a line <br />
<tt>]</tt> <br />
#       XML namespace prefix definitions can be provided to override the <br />
#       default choice of ns1, ns2, ... prefixes. For example: <br />
 <br />
i       = "http://www.soapinterop.org/" <br />
s       = "http://www.soapinterop.org/xsd"
</td></tr></table><br></tt>

<div class="p"><!----></div>
Type bindings can be provided to bind XML schema types to C/C++
types for your project.
Type bindings have four parts:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
prefix__type = declaration &#124; use &#124; ptr-use
</td></tr></table><br></tt>
where 'prefix__type' is the C/C++-translation of the schema type,
'declaration' introduces the C/C++ type in the header file, the optional
'use' specifies how the type is used directly, and the optional
'ptr-use' specifies how the type is used as a pointer type.

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
#       Example XML Schema and C/C++ type bindings: <br />
 <br />
xsd__int        = &#124; int <br />
xsd__string     = &#124; char* &#124; char* <br />
xsd__boolean = enum xsd__boolean  false_, true_ ; &#124; enum xsd__boolean <br />
xsd__base64Binary = class xsd__base64Binary  unsigned char *__ptr; int __size; ; &#124; xsd__base64Binary &#124; xsd__base64Binary <br />
#	You can extend structs and classes with member data and functions. <br />
#      For example, adding a constructor to ns__myClass:
ns__myClass     = $ ns__myClass(); <br />
#	The general form is
#	class_name = $ member; <br />
</td></tr></table><br></tt>
The <i>i</i> and <i>s</i> prefixes are declared such that the header file output by the WSDL parser will use these to produce C/C++ code.
XML Schema types are associated with an optional C/C++ type declaration, a use reference, and a pointer-use reference. The pointer-use reference of the <i>xsd__byte</i> type for example, is <i><b>int</b>*</i> because <i><b>char</b>*</i> is reserved for strings.

<div class="p"><!----></div>
When a type binding requires only the usage to be changed, the
declaration part can be given by an elipsis ..., as in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
prefix__type = ... &#124; use &#124; ptr-use
</td></tr></table><br></tt>
This ensures that the wsdl2h-generated type definition is preserved,
while the use and ptr-use are remapped.

<div class="p"><!----></div>
This method is useful to serialize dynamic types in C, where elements types int
XML carry the <tt>xsi:type</tt> attribute.

<div class="p"><!----></div>
The following example illustrates an "any" type mapping for the
<tt>ns:sometype</tt> XSD type in a schema. This type will be replaced with a "any"
type wrapper that supports dynamic serialization with <tt>xsi:type</tt>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
[ <br />
struct __any <br />
{ <br />
&nbsp;&nbsp;&nbsp;int __type; <br />
&nbsp;&nbsp;&nbsp;void *__item; <br />
} <br />
] <br />
xsd__anyType = ... &#124; struct __any &#124; struct __any
</td></tr></table><br></tt>
where <tt>__type</tt> and <tt>__item</tt> are used to (de)serialize any data type in the wrapper,
including base and its derived types based on <tt>xsi:type</tt> attribuation.

<div class="p"><!----></div>
To support complexType extensions that are dynamically bound in C code, i.e.
polymorphic types based on inheritance hierarchies, we can redeclare the base
type of a hierarchy as a wrapper type and use the <i>__type</i> to serialize
base or derived types. One addition is needed to support base type
serialization without the use of <tt>xsi:type</tt> attributes. The absence of this attribute requires the serialization of the base type.

<div class="p"><!----></div>
Basically, we need to be able to both handle a base type and its extensions
as per schema extensibility. Say base type <tt>ns:base</tt> is a complexType that is extended by several other complexTypes. To implement dynamic binding in C to serialize the base type and derived types, we define:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
[ <br />
struct __ns__base <br />
{ <br />
&nbsp;&nbsp;&nbsp;int __type; <br />
&nbsp;&nbsp;&nbsp;void *__item; <br />
&nbsp;&nbsp;&nbsp;struct ns__base *__self; <br />
} <br />
] <br />
ns__base = ... &#124; struct __ns__base &#124; struct __ns__base
</td></tr></table><br></tt>
The <tt>__self</tt> field refers to the element tag (basically a struct member name)
to which the <tt>ns:base</tt> type is associated. So for example, we see in the soapcpp2-generated output:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__data <br />
{ <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;__ns__base name; <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
where <i>__item</i> represents <i>name</i> when the <i>__ns__base</i> is
serialized with an <tt>xsi:type</tt> attribute, and <i>__self</i> represents
<i>name</i> when the <i>__ns__base</i> is serialized wwithout an <tt>xsi:type</tt>
attribute. Therefore, the dynamic binding defaults to <i><b>struct</b>&nbsp;ns__base
*__self</i> when no dynamic type information in XML is available.

<div class="p"><!----></div>
Additional data and function members can be provided to extend a
generated struct or class.
Class and struct extensions are of the form:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
prefix__type = $ member-declaration
</td></tr></table><br></tt>
For example, to add a constructor and destructor to class myns__record:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
myns__record = $ myns__record();
myns__record = $ ~myns__record();
</td></tr></table><br></tt>

<div class="p"><!----></div>
Type remappings can be given to map a type to another type:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
prefix__type1 == prefix__type2
</td></tr></table><br></tt>
which replaces <tt>prefix__type1</tt> by <tt>prefix__type2</tt> in the wsdl2h output.
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
SOAP_ENC__boolean == xsd__boolean
</td></tr></table><br></tt>
where <tt>SOAP_ENC__boolean</tt> is mapped to <tt>xsd__boolean</tt>, which in turn may be mapped to a C <tt><b>enum</b>&nbsp;xsd__boolean</tt> type or C++ <tt>bool</tt> type.

<div class="p"><!----></div>
 <h2><a name="tth_sEc9">
9</a>&nbsp;&nbsp;<font color="#0000FF">Using the soapcpp2 Compiler and Code Generator</font></h2><a name="sec:soapcpp2">
</a>

<div class="p"><!----></div>
The <i>soapcpp2</i> compiler and code generator is invoked from the command line
and optionally takes the name of a header file as an argument or, when the file
name is absent, parses the standard input:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 <font size="+1"><span class="roman">[</span></font>aheaderfile.h<font size="+1"><span class="roman">]</span></font></i>
</td></tr></table><br></span>
where <i>aheaderfile.h</i> is a C/C++ header file generated by <i>wsdl2h</i> or
developed manually to specify the SOAP/XML service operations as function
prototypes and the C/C++ data types to be auto-mapped to XML.

<div class="p"><!----></div>
The <i>soapcpp2</i> tool produces C/C++ source files. These files are used to
implement SOAP/XML clients and services, and to implement the advanced XML data
binding logic to convert C/C++ data into XML and vice versa.

<div class="p"><!----></div>
The type of files generated by <i>soapcpp2</i> are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>File Name</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>soapStub.h</i> </td><td align="left">A modified and annotated header file produced from the input header file </td></tr>
<tr><td align="left"><i>soapH.h</i> </td><td align="left">Main header file to be included by all client and service sources </td></tr>
<tr><td align="left"><i>soapC.cpp</i> </td><td align="left">Serializers and deserializers for the specified data structures </td></tr>
<tr><td align="left"><i>soapClient.cpp</i> </td><td align="left">Client stub routines for remote operations </td></tr>
<tr><td align="left"><i>soapServer.cpp</i> </td><td align="left">Service skeleton routines </td></tr>
<tr><td align="left"><i>soapClientLib.cpp</i> </td><td align="left">Client stubs combined with local static (de)serializers </td></tr>
<tr><td align="left"><i>soapServerLib.cpp</i> </td><td align="left">Service skeletons combined with local static (de)serializers </td></tr>
<tr><td align="left"><i>soapXYZProxy.h</i> </td><td align="left">A C++ proxy object (link with soapC.cpp soapClient.cpp) </td></tr>
<tr><td align="left"><i>soapXYZProxy.h</i> </td><td align="left">With option -i: proxy object (link with soapC.cpp and soapXYZProxy.cpp) </td></tr>
<tr><td align="left"><i>soapXYZProxy.cpp</i> </td><td align="left">With option -i: proxy code </td></tr>
<tr><td align="left"><i>soapXYZObject.h</i> </td><td align="left">A C++ server object (link with soapC.cpp and soapServer.cpp) </td></tr>
<tr><td align="left"><i>soapXYZService.h</i> </td><td align="left">With option -i: server object (link with soapC.cpp and soapXYZService.cpp) </td></tr>
<tr><td align="left"><i>soapXYZService.cpp</i> </td><td align="left">With option -i: server code </td></tr>
<tr><td align="left"><i>.xsd</i> </td><td align="left">An <i>ns.xsd</i> file is generated with an XML Schema for each namespace prefix <i>ns</i> used by a data structure in the header
file input to the compiler, see Section&nbsp;<a href="#sec:wsdl">7.2.9</a> </td></tr>
<tr><td align="left"><i>.wsdl</i> </td><td align="left">A <i>ns.wsdl</i> file is generated with an WSDL description for each namespace prefix <i>ns</i> used by a service operation in the
header file input to the compiler, see Section&nbsp;<a href="#sec:wsdl">7.2.9</a> </td></tr>
<tr><td align="left"><i>.xml</i> </td><td align="left">Several SOAP/XML request and response files are generated. These are example message files are valid provided
that sufficient schema namespace directives are added to the header file or the generated .nsmap namespace table for the
client/service is not modified by hand </td></tr>
<tr><td align="left"><i>.nsmap</i> </td><td align="left">A <i>ns.nsmap</i> file is generated for each namespace prefix <i>ns</i> used by a service operation in the
header file input to the compiler, see Section&nbsp;<a href="#sec:wsdl">7.2.9</a>.  The file contains a namespace mapping table that can be used in the client/service sources </td></tr></table>

</td></tr></table><br></span>
Both client and service applications are developed from a header file that
specifies the service operations. If client and service applications are
developed with the same header file, the applications are guaranteed to be
compatible because the stub and skeleton routines use the same serializers and
deserializers to encode and decode the parameters. Note that when client and
service applications are developed together, an application developer does not
need to know the details of the internal SOAP encoding used by the client and
service.

<div class="p"><!----></div>
The <i>soapClientLib.cpp</i> and <i>soapServerLib.cpp</i> can be used to build (dynamic) client and server libraries. The serialization routines are local (static) to avoid link symbol conflicts. You must create a separate library for SOAP Header and Fault handling, as described in Section&nbsp;<a href="#sec:dylibs">19.36</a>.

<div class="p"><!----></div>
The following files are part of the gSOAP package and are required to build client and service applications:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>File Name</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>stdsoap2.h</i> </td><td align="left">Header file of <i>stdsoap2.cpp</i> runtime library </td></tr>
<tr><td align="left"><i>stdsoap2.c</i> </td><td align="left">Runtime C library with XML parser and run-time support routines </td></tr>
<tr><td align="left"><i>stdsoap2.cpp</i> </td><td align="left">Runtime C++ library identical to <i>stdsoap2.c</i> </td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.1">
9.1</a>&nbsp;&nbsp;<font color="#0000FF">soapcpp2 Options</font></h3><a name="sec:options">
</a>

<div class="p"><!----></div>
The <i>soapcpp2</i> source-to-source compiler supports the following command-line options:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Option</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>-1</i>	</td><td align="left">Generate SOAP 1.1 bindings </td></tr>
<tr><td align="left"><i>-2</i>	</td><td align="left">Generate SOAP 1.2 bindings </td></tr>
<tr><td align="left"><i>-0</i>	</td><td align="left">No SOAP bindings, use REST</td></tr>
<tr><td align="left"><i>-C</i>	</td><td align="left">Generate client-side code only </td></tr>
<tr><td align="left"><i>-S</i>	</td><td align="left">Generate server-side code only </td></tr>
<tr><td align="left"><i>-T</i>	</td><td align="left">Generate server auto-test code </td></tr>
<tr><td align="left"><i>-L</i>	</td><td align="left">Do not generate soapClientLib/soapServerLib </td></tr>
<tr><td align="left"><i>-a</i>	</td><td align="left">Use SOAPAction with WS-Addressing to invoke server-side operations </td></tr>
<tr><td align="left"><i>-A</i>	</td><td align="left">Require SOAPAction to invoke server-side operations </td></tr>
<tr><td align="left"><i>-b</i>	</td><td align="left">serialize byte arrays <i>char[N]</i> as string </td></tr>
<tr><td align="left"><i>-c</i>	</td><td align="left">Generate pure C code </td></tr>
<tr><td align="left"><i>-d  &lt; path &gt; </i>	</td><td align="left">Save sources in directory specified by <i> &lt; path &gt; </i> </td></tr>
<tr><td align="left"><i>-e</i>	</td><td align="left">Generate SOAP RPC encoding style bindings </td></tr>
<tr><td align="left"><i>-f N</i>	</td><td align="left">File split of N XML serializer implementations per file </td></tr>
<tr><td align="left"><i>-h</i>	</td><td align="left">Print a brief usage message </td></tr>
<tr><td align="left"><i>-i</i>	</td><td align="left">Generate service proxies and objects inherited from soap struct </td></tr>
<tr><td align="left"><i>-j</i>	</td><td align="left">Generate C++ service proxies and objects that can share a soap struct </td></tr>
<tr><td align="left"><i>-I  &lt; path &gt; </i>	</td><td align="left">Use <i> &lt; path &gt; </i> for <i>#import</i> (paths separated with ':' or ';' for windows) </td></tr>
<tr><td align="left"><i>-k</i>	</td><td align="left">generate data structure walkers (experimental) </td></tr>
<tr><td align="left"><i>-l</i>	</td><td align="left">Generate linkable modules (experimental) </td></tr>
<tr><td align="left"><i>-m</i>	</td><td align="left">Generate Matlab<sup><span class="roman">tm</span></sup> code for MEX compiler </td></tr>
<tr><td align="left"><i>-n</i>	</td><td align="left">When used with <i>-p</i>, enables multi-client and multi-server builds: </td></tr>
<tr><td align="left"></td><td align="left">Sets compiler option <i>WITH_NONAMESPACES</i>, see Section&nbsp;<a href="#sec:compilerflags">9.11</a> </td></tr>
<tr><td align="left"></td><td align="left">Saves the namespace mapping table with name <i> &lt; name &gt; _namespaces</i> instead of <i>namespaces</i> </td></tr>
<tr><td align="left"></td><td align="left">Renames <i>soap_serve()</i> into <i> &lt; name &gt; _serve()</i> and <i>soap_destroy()</i> into <i> &lt; name &gt; _destroy()</i> </td></tr>
<tr><td align="left"><i>-p  &lt; name &gt; </i>	</td><td align="left">Save sources with file name prefix <i> &lt; name &gt; </i> instead of "<i>soap</i>" </td></tr>
<tr><td align="left"><i>-q  &lt; name &gt; </i>	</td><td align="left">Use <i>name</i> for the C++ namespace of all declarations </td></tr>
<tr><td align="left"><i>-s</i>	</td><td align="left">Generates deserialization code with strict XML validation checks </td></tr>
<tr><td align="left"><i>-t</i>	</td><td align="left">Generates code to send typed messages (with the <tt>xsi:type</tt> attribute) </td></tr>
<tr><td align="left"><i>-u</i>	</td><td align="left">uncomment comments in WSDL/schema output by suppressing XML comments </td></tr>
<tr><td align="left"><i>-v</i>	</td><td align="left">Display version info</td></tr>
<tr><td align="left"><i>-w</i>	</td><td align="left">Do not generate WSDL and schema files </td></tr>
<tr><td align="left"><i>-x</i>	</td><td align="left">Do not generate sample XML message files </td></tr>
<tr><td align="left"><i>-y</i>	</td><td align="left">include C/C++ type access information in sample XML messages </td></tr>
<tr><td align="left"><i>-z1</i>	</td><td align="left">compatibility: generate old-style C++ service proxies and objects </td></tr>
<tr><td align="left"><i>-z2</i>	</td><td align="left">compatibility with 2.7.x: omit XML output for NULL pointers </td></tr></table>

</td></tr></table><br></span>
For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -cd '../projects' -pmy file.h</i>
</td></tr></table><br></span>
Saves the sources:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i>../projects/myH.h</i> <br />
<i>../projects/myC.c</i> <br />
<i>../projects/myClient.c</i> <br />
<i>../projects/myServer.c</i> <br />
<i>../projects/myStub.h</i> <br />
</td></tr></table><br></span>
MS Windows users can use the usual "<i>/</i>" for options, for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i>soapcpp2 /cd '..\projects' /pmy file.h</i>
</td></tr></table><br></span>
Compiler options <i>c, i, n, l, w</i> can be set in the gSOAP header file using the <i>//gsoapopt</i> directive. For example,
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Generate pure C and do not produce WSDL output: <br />
//gsoapopt cw <br />
<b>int</b>&nbsp;ns__myMethod(<b>char</b>*,<b>char</b>**); // takes a string and returns a string
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.2">
9.2</a>&nbsp;&nbsp;<font color="#0000FF">SOAP 1.1 Versus SOAP 1.2 and Dynamic Switching</font></h3>

<div class="p"><!----></div>
gSOAP supports SOAP 1.1 by default. SOAP 1.2 support is automatically turned on when the appropriate SOAP 1.2 namespace is used, which shows up in
the namespace mapping table:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{ <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://www.w3.org/2003/05/soap-envelope", ... }, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC", "http://www.w3.org/2003/05/soap-encoding, ... "}, <br />
&nbsp;&nbsp;&nbsp;... <br />
}
</td></tr></table><br></i>
Normally the <i>soapcpp2</i>-generated namespace table allows dynamic switching between SOAP 1.1 to SOAP 1.2 by providing the SOAP 1.2 namespace
as a <b>pattern</b> in the third column of a namespace table:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{ <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/", "http://www.w3.org/*/soap-encoding"}, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/", "http://www.w3.org/*/soap-envelope"}, <br />
&nbsp;&nbsp;&nbsp;... <br />
}
</td></tr></table><br></i>
where the "<i>*</i>" in the third column of the namespace URI pattern is a meta wildcard. This is used to match and accept inbound namespaces.

<div class="p"><!----></div>
This way, gSOAP Web services can respond to either SOAP 1.1 or SOAP 1.2 requests.  gSOAP will automatically return SOAP 1.2 responses for SOAP 1.2 requests.

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> tool generates a <i>.nsmap</i> file with <i>SOAP-ENV</i> and <i>SOAP-ENC</i> namespace patterns similar to the above.
Since clients issue a send first, they will always use SOAP 1.1 for requests when the namespace table is similar as shown above.
Clients can accept SOAP 1.2 responses by inspecting the response message.

<div class="p"><!----></div>
To use SOAP 1.2 by default and allow SOAP 1.1 messages to be received, use the <i>soapcpp2 -2</i> option to generate SOAP 1.2 conformant <i>.nsmap</i> and <i>.wsdl</i> files. Alternatively, add the following line to your service definitions header file (generated by <i>wsdl2h</i>) for <i>soapcpp2</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "import/soap12.h"
</td></tr></table><br></i>

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: SOAP 1.2 does not support partially transmitted arrays. So the <i>__offset</i> field of a dynamic array is meaningless.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: SOAP 1.2 requires the use of <i>SOAP_ENV__Code</i>, <i>SOAP_ENV__Reason</i>, and <i>SOAP_ENV__Detail</i> fields
in a <i>SOAP_ENV__Fault</i> fault struct, while SOAP 1.1 uses <i>faultcode</i>, <i>faultstring</i>, and <i>detail</i> fields.
Use <i>soap_receiver_fault_subcode(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*subcode, <b>const</b>&nbsp;<b>char</b>&nbsp;*faultstring, <b>const</b>&nbsp;<b>char</b>&nbsp;*detail)</i> to set a SOAP 1.1/1.2
fault at the server-side with a fault subcode (SOAP 1.2).
Use <i>soap_sender_fault_subcode(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*subcode, <b>const</b>&nbsp;<b>char</b>&nbsp;*faultstring, <b>const</b>&nbsp;<b>char</b>&nbsp;*detail)</i> to set a SOAP 1.1/1.2
unrecoverable Bad Request fault at the server-side with a fault subcode (SOAP 1.2).

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.3">
9.3</a>&nbsp;&nbsp;<font color="#0000FF">The soapdefs.h Header File</font></h3><a name="sec:soapdefs">
</a>

<div class="p"><!----></div>
The <i>soapdefs.h</i> header file is included in <i>stdsoap2.h</i> when compiling with option <i>-DWITH_SOAPDEFS_H</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -DWITH_SOAPDEFS_H -c stdsoap2.cpp</i>
</td></tr></table><br></span>
The <i>soapdefs.h</i> file allows users to include definitions and add includes without requiring changes to <i>stdsoap2.h</i>.
For example,
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of soapdefs.h <br />
#include  &lt; ostream &gt;  <br />
#define SOAP_BUFLEN 65536 // use large send/recv buffer <br />
</td></tr></table><br></i>
The following header file can now refer to <i>ostream</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>extern</b>&nbsp;<b>class</b>&nbsp;ostream; // ostream can't be (de)serialized, but need to be declared to make it visible to gSOAP <br />
<b>class</b>&nbsp;ns__myClass <br />
{ ... <br />
&nbsp;&nbsp;&nbsp;<b>virtual</b>&nbsp;<b>void</b>&nbsp;print(ostream &amp;s) <b>const</b>; // need ostream here <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
See also Section&nbsp;<a href="#sec:transient">19.3</a>.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.4">
9.4</a>&nbsp;&nbsp;<font color="#0000FF">How to Build Modules and Libraries with the #module Directive</font></h3><a name="sec:module">
</a>

<div class="p"><!----></div>
The <i>#module</i> directive is used to build modules. A library can be build from a module and linked with multiple Web services applications. The directive should appear at the top of the header file and has the following formats:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#module "<i>name</i>" <br />
</td></tr></table><br></i>
and
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#module "<i>name</i>" "<i>fullname</i>"<br />
</td></tr></table><br></i>
where <i>name</i> must be a unique short name for the module. The name is case insensitive and MUST not exceed 4 characters in length. The <i>fullname</i>, when present, represents the full name of the module.

<div class="p"><!----></div>
The rest of the content of the header file includes type declarations and optionally the declarations of service operations and SOAP Headers/Faults. When the gSOAP <i>soapcpp2</i> compiler processes the header file module, it will generate the source codes for a library. The Web services application that uses the library should use a header file that imports the module with the <i>#import</i> directive.

<div class="p"><!----></div>
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
/* Contents of module.h */ <br />
#module "test"<br />
<b>long</b>; <br />
<b>char</b>*; <br />
<b>struct</b>&nbsp;ns__S <br />
{ ... }
</td></tr></table><br></i>
The <i>module.h</i> header file declares a <b>long</b>, <b>char</b>*, and a <i><b>struct</b>&nbsp;ns__X</i>. The module name is "test", so the gSOAP <i>soapcpp2</i> compiler produces a <i>testC.cpp</i> file with the (de)serializers for these types. The <i>testC.cpp</i> library can be separately compiled and linked with an application that is built from a header file that imports "module.h" using <i>#import "module.h"</i>. You should also compile <i>testClient.cpp</i> when you want to build a library that includes the service opertions that you defined in the module header file.

<div class="p"><!----></div>
There are some limitations on a sequence of module imports. A module MUST be imported into another header to use the module content and you MUST place this import statement before all other statements in the file, including other imports (except when these are also modules). It is also advised to put all basic data type definitions in the root module of a module import hierarchy, e.g. using <i><b>typedef</b></i> to declare XSD types (see also Section&nbsp;<a href="#sec:primitive">11.3</a>).

<div class="p"><!----></div>
You cannot use a module alone to build a SOAP or XML application. That is, the final gSOAP header file in the import chain SHOULD NOT be a module.

<div class="p"><!----></div>
When multiple modules are linked, the types that they declare MUST be declared in one module only to avoid name clashes and link errors. You cannot create two modules that share the same type declaration and link the modules. When necessary, you should consider creating a module hierarchy such that types are declared only once and by only one module when these modules must be linked.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.5">
9.5</a>&nbsp;&nbsp;<font color="#0000FF">How to use the #import Directive</font></h3><a name="sec:import">
</a>

<div class="p"><!----></div>
The <i>#import</i> directive is used to include gSOAP header files into other gSOAP header files for processing with
the gSOAP compiler <i>soapcpp2</i>.
The C <i>#include</i> directive cannot be used to include gSOAP header files.
The <i>#include</i> directive is reserved to control the post-gSOAP compilation process, see&nbsp;<a href="#sec:pragmas">9.6</a>.

<div class="p"><!----></div>
The <i>#import</i> directive is used for two purposes: you can use it to include the contents of a header file into another header file and you can use it to import a module, see&nbsp;<a href="#sec:module">9.4</a>.

<div class="p"><!----></div>
An example of the <i>#import</i> directive:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "mydefs.gsoap" <br />
<b>int</b>&nbsp;ns__mymethod(xsd__string in, xsd__int *out);
</td></tr></table><br></i>
where <i>"mydefs.gsoap"</i> is a gSOAP header file that defines <i>xsd__string</i> and <i>xsd__int</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string; <br />
<b>typedef</b>&nbsp;<b>int</b>&nbsp;xsd__int;
</td></tr></table><br></i>

<div class="p"><!----></div>
When importing a module, where the module content is declared with <i>#module</i>, then note that this module MUST place the import statement before all other statements in the header file, including other imports (except when these are also modules).

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.6">
9.6</a>&nbsp;&nbsp;<font color="#0000FF">How to Use #include and #define Directives</font></h3><a name="sec:pragmas">
</a>

<div class="p"><!----></div>
The <i>#include</i> and <i>#define</i> directives are normally ignored by the gSOAP <i>soapcpp2</i> compiler and just passed on to the generated code.
Thus, the gSOAP compiler will not actually parse the contents of the header files provided by the <i>#include</i> directives in a header file.
Instead, the <i>#include</i> and <i>#define</i> directives will be added to the generated <i>soapH.h</i> header file <b>before</b>
any other header file is included. Therefore, <i>#include</i> and <i>#define</i> directives can be used to control the C/C++
compilation process of the sources of an application. However, they have no effect on <i>soapcpp2</i>.

<div class="p"><!----></div>
The following example header file refers to <i>ostream</i> by including <i> &lt; ostream &gt; </i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include  &lt; ostream &gt;  <br />
#define WITH_COOKIES // use HTTP cookie support (you must compile stdsoap2.cpp with -DWITH_COOKIES) <br />
#define WITH_OPENSSL // enable HTTPS/SSL support (you must compile stdsoap2.cpp with -DWITH_OPENSSL) <br />
#define WITH_GNUTLS // enable HTTPS/SSL support (you must compile stdsoap2.cpp with -DWITH_GNUTLS) <br />
#define SOAP_DEFAULT_float FLT_NAN // use NaN instead of 0.0 <br />
<b>extern</b>&nbsp;<b>class</b>&nbsp;ostream; // ostream can't be (de)serialized, but need to be declared to make it visible to gSOAP <br />
<b>class</b>&nbsp;ns__myClass <br />
{ ... <br />
&nbsp;&nbsp;&nbsp;<b>virtual</b>&nbsp;<b>void</b>&nbsp;print(ostream &amp;s) <b>const</b>; // need ostream here <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
This example also uses <i>#define</i> directives for various settings in the target source code.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: Note that the use of <i>#define</i> in the header file does not automatically result in compiling
<i>stdsoap2.cpp</i> with these directives. You MUST use the <i>-DWITH_COOKIES</i> and <i>-DWITH_OPENSSL</i> (or <i>-DWITH_GNUTLS</i> options when
compiling <i>stdsoap2.cpp</i> before linking the object file with your codes. As an alternative, you can use <i>#define
WITH_SOAPDEFS_H</i> and put the <i>#define</i> directives in the <i>soapdefs.h</i> file.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.7">
9.7</a>&nbsp;&nbsp;<font color="#0000FF">Compiling a SOAP/XML Client Application with soapcpp2</font></h3>

<div class="p"><!----></div>
After invoking the gSOAP <i>soapcpp2</i> tool on a header file description of a service, the client application can be compiled on a Linux machine as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -o myclient myclient.cpp stdsoap2.cpp soapC.cpp soapClient.cpp</i>
</td></tr></table><br></span>
Or on a Unix machine:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -o myclient myclient.cpp stdsoap2.cpp soapC.cpp soapClient.cpp -lsocket -lxnet -lnsl</i>
</td></tr></table><br></span>
(Depending on your system configuration, the libraries <i>libsocket.a</i>,
<i>libxnet.a</i>, <i>libnsl.a</i> or dynamic <i>*.so</i> versions of those libraries are required.)

<div class="p"><!----></div>
The <i>myclient.cpp</i> file must include <i>soapH.h</i> and must define a global namespace mapping table. A typical client program layout with namespace mapping table is shown below:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "myclient.cpp" <br />
#include "soapH.h"; <br />
... <br />
// A service operation invocation: <br />
&nbsp;&nbsp;&nbsp;soap_call_some_remote_method(...); <br />
... <br />
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{&nbsp;&nbsp;&nbsp;// {"ns-prefix", "ns-name"} <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/"}, <br />
&nbsp;&nbsp;&nbsp;{"xsi",      "http://www.w3.org/2001/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd",      "http://www.w3.org/2001/XMLSchema"}, <br />
&nbsp;&nbsp;&nbsp;{"ns1",      "urn:my-remote-method"}, <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} <br />
}; <br />
...
</td></tr></table><br></i>
A mapping table is generated by the gSOAP <i>soapcpp2</i> compiler that can be used in the source, see Section&nbsp;<a href="#sec:wsdl">7.2.9</a>.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.8">
9.8</a>&nbsp;&nbsp;<font color="#0000FF">Compiling a SOAP/XML Web Service with soapcpp2</font></h3>

<div class="p"><!----></div>
After invoking the gSOAP <i>soapcpp2</i> tool on a header file description of the service, the server application can be compiled on a Linux machine as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -o myserver myserver.cpp stdsoap2.cpp soapC.cpp soapServer.cpp</i>
</td></tr></table><br></span>
Or on a Unix machine:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -o myserver myserver.cpp stdsoap2.cpp soapC.cpp soapServer.cpp -lsocket -lxnet -lnsl</i>
</td></tr></table><br></span>
(Depending on your system configuration, the libraries <i>libsocket.a</i>,
<i>libxnet.a</i>, <i>libnsl.a</i> or dynamic <i>*.so</i> versions of those libraries are required.)

<div class="p"><!----></div>
The <i>myserver.cpp</i> file must include <i>soapH.h</i> and must define a global namespace mapping table. A typical service program layout with namespace mapping table is shown below:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "myserver.cpp" <br />
#include "soapH.h"; <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_serve(soap_new()); <br />
} <br />
... <br />
// Implementations of the service operations as C++ functions <br />
... <br />
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{&nbsp;&nbsp;&nbsp;// {"ns-prefix", "ns-name"} <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/"}, <br />
&nbsp;&nbsp;&nbsp;{"xsi",      "http://www.w3.org/2001/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd",      "http://www.w3.org/2001/XMLSchema"}, <br />
&nbsp;&nbsp;&nbsp;{"ns1",      "urn:my-remote-method"}, <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} <br />
}; <br />
...
</td></tr></table><br></i>
When the gSOAP service is compiled and installed as a CGI application, the <i>soap_serve</i> function acts as a service dispatcher. It listens to standard input and
invokes the method via a skeleton routine to serve a SOAP client request. After the request is served, the response is encoded in
SOAP and send to standard output. The method must be implemented in the server application and the type signature of the method
must be identical to the service operations specified in the header file. That is, the function prototype in the header file must be a
valid prototype of the method implemented as a C/C++ function.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.9">
9.9</a>&nbsp;&nbsp;<font color="#0000FF">Compiling Web Services and Clients in ANSI C</font></h3>

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> compiler can be used to create pure C Web services and clients. The gSOAP stub and skeleton compiler
<i>soapcpp2</i> generates <i>.cpp</i> files by default. The compiler generates <i>.c</i> files with the <i>-c</i> option.
However, these files only use C syntax and data types <b>if</b> the header
file input to <i>soapcpp2</i> uses C syntax and data types. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -c quote.h</i> <br />
<i> &gt;  cc -o quote quote.c stdsoap2.c soapC.c soapClient.c</i>
</td></tr></table><br></span>
Warnings will be issued by the compiler when C++ class declarations occur in the header file.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.10">
9.10</a>&nbsp;&nbsp;<font color="#0000FF">Limitations of gSOAP</font></h3><a name="sec:limitations">
</a>

<div class="p"><!----></div>
gSOAP is SOAP 1.1 and SOAP 1.2 compliant and supports SOAP RPC and document/literal operations.

<div class="p"><!----></div>
From the perspective of the C/C++ language, a few C++ language features are not supported by gSOAP and these features cannot be used in the specification of SOAP service operations.

<div class="p"><!----></div>
There are certain limitations for the following C++ language constructs:

<dl compact="compact">
 <dt><b>STL and STL templates</b></dt>
	<dd> The gSOAP <i>soapcpp2</i> compiler supports C++ strings <i>std::string</i> and <i>std::wstring</i> (see Section&nbsp;<a href="#sec:strings">11.3.6</a>) and the STL containers <i>std::deque</i>, <i>std::list</i>, <i>std::vector</i>, and <i>std::set</i>, (see Section&nbsp;<a href="#sec:templates">11.11.8</a>).</dd>
 <dt><b>Templates</b></dt>
	<dd> The gSOAP <i>soapcpp2</i> compiler is a preprocessor that cannot determine the template instantiations used by the main program, nor can it generate templated code. You can however implement containers similar to the STL containers.</dd>
 <dt><b>Multiple inheritance</b></dt>
	<dd> Single class inheritance is supported. Multiple inheritance cannot be supported due to limitations of the SOAP protocol.</dd>
 <dt><b>Abstract methods</b></dt>
	<dd> A class must be instantiatable to allow decoding of instances of the class.</dd>
 <dt><b>Directives</b></dt>
	<dd> Directives and pragmas such as <i>#include</i> and <i>#define</i> are interpreted by the gSOAP <i>soapcpp2</i> compiler.
However, the interpretation is different compared to the usual handling of directives, see Section&nbsp;<a href="#sec:pragmas">9.6</a>. If necessary, a traditional C++
preprocessor can be used for the interpretation of directives. For example, Unix and Linux users can use "<tt>cpp -B</tt>"
to expand the header file, e.g. <tt>cpp -B myfile.h  -  soapcpp2</tt>.
Use the gSOAP <i>#import</i> directive to import gSOAP header files, see&nbsp;<a href="#sec:import">9.5</a>.</dd>
 <dt><b>C and C++ programming statements</b></dt>
	<dd> All class methods of a class should be declared within the class declaration in the header file, but the methods should not be implemented in code. All class method implementations must be defined within another C++ source file and linked to the application.</dd>
</dl>
The following data types require some attention to ensure they are serialized:

<dl compact="compact">
 <dt><b><i><b>union</b></i> types</b></dt>
	<dd> A <i><b>union</b></i> data type can not be serialized unless run-time information is associated with a <i><b>union</b></i> in a struct/class as discussed in Section&nbsp;<a href="#sec:union">11.7</a>. An alternative is to use a <i><b>struct</b></i> with a pointer type for each field. Because <i>NULL</i> pointers are not encoded, the resulting encoding will appear as a union type if only one pointer field is valid (i.e.&nbsp;non-<i>NULL</i>) at the time that the data type is encoded.</dd>
 <dt><b><i><b>void</b></i> and <i><b>void</b>*</i> types</b></dt>
	<dd> The <i><b>void</b></i> data type cannot be serialized unless run-time type information is associated with the pointer using a <i><b>int</b>&nbsp;__type</i> field in the struct/class that contains the <i><b>void</b>*</i>. The <i><b>void</b>*</i> data type is typically used to point to some object or to some array of some type of objects at run-time. The compiler cannot determine the type of data pointed to and the size of the array pointed to. A struct or class with a <i><b>void</b>*</i> field can be augmented to support the (de)serialization of the <i><b>void</b>*</i> using a <i><b>int</b>&nbsp;__type</i> field as described in Section&nbsp;<a href="#sec:void">11.9</a>.</dd>
 <dt><b>Pointers to sequences of elements in memory</b></dt>
	<dd> Any pointer, except for C strings which are pointers to a sequence of
characters, are treated by the compiler as if the pointer points to <b>only one element in memory</b> at run-time. Consequently,
the encoding and decoding routines will ignore any subsequent elements that follow the first in memory. For the same reason,
arrays of undetermined length, e.g.&nbsp;<i><b>float</b>&nbsp;a[]</i> cannot be used. gSOAP supports dynamic arrays using a special type convention,
see Section&nbsp;<a href="#sec:dynarray">11.11</a>.</dd>
 <dt><b>Uninitialized pointers</b></dt>
	<dd> Obviously, all pointers that are part of a data structure must be valid or <i>NULL</i> to enable
serialization of the data structure at run time.</dd>
</dl>
There are a number of programming solutions that can be adopted to circumvent these limitations. Instead of using <i><b>void</b>*</i>, a program
can in some cases be modified to use a pointer to a known type. If the pointer is intended to point to different types of objects, a generic
base class can be declared and the pointer is declared to point to the base class. All the other types are declared to be derived
classes of this base class. For pointers that point to a sequence of elements in memory dynamic arrays should be used instead,
see <a href="#sec:dynarray">11.11</a>.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.11">
9.11</a>&nbsp;&nbsp;<font color="#0000FF">Library Build Flags</font></h3><a name="sec:compilerflags">
</a>

<div class="p"><!----></div>
The following macros (<i>#define</i>s) can be used to enable certain optional features when building the <i>libgsoap</i> library or when compiling and linking <i>stdsoap2.c</i> and <i>stdsoap2.cpp</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Macro</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>WITH_SOAPDEFS_H</i>	</td><td align="left">includes the <i>soapdefs.h</i> file for custom settings, see Section&nbsp;<a href="#sec:soapdefs">9.3</a> </td></tr>
<tr><td align="left"><i>WITH_COOKIES</i>	</td><td align="left">enables HTTP cookies, see Sections&nbsp;<a href="#sec:clientcookie">19.28</a>&nbsp;<a href="#sec:servercookie">19.29</a> </td></tr>
<tr><td align="left"><i>WITH_OPENSSL</i>	</td><td align="left">enables OpenSSL, see Sections&nbsp;<a href="#sec:clientopenssl">19.22</a>&nbsp;<a href="#sec:serveropenssl">19.21</a> </td></tr>
<tr><td align="left"><i>WITH_GNUTLS</i>	</td><td align="left">enables GNUTLS, see Sections&nbsp;<a href="#sec:clientopenssl">19.22</a>&nbsp;<a href="#sec:serveropenssl">19.21</a> </td></tr>
<tr><td align="left"><i>WITH_IPV6</i>	</td><td align="left">enables IPv6 support (compile ALL sources with this macro set)</td></tr>
<tr><td align="left"><i>WITH_IPV6_V6ONLY</i></td><td align="left">IPv6-only server option (compile ALL sources with this macro set)</td></tr>
<tr><td align="left"><i>WITH_NO_IPV6_V6ONLY</i></td><td align="left">resets IPv6-only server option (compile ALL sources with this macro set)</td></tr>
<tr><td align="left"><i>WITH_TCPFIN</i>	</td><td align="left">use TCP FIN after sends when socket is ready to close </td></tr>
<tr><td align="left"><i>WITH_FASTCGI</i>	</td><td align="left">enables FastCGI, see Sections&nbsp;<a href="#sec:fastcgi">19.31</a> </td></tr>
<tr><td align="left"><i>WITH_GZIP</i>	</td><td align="left">enables gzip and deflate compression, see Section&nbsp;<a href="#sec:compression">19.27</a> </td></tr>
<tr><td align="left"><i>WITH_ZLIB</i>	</td><td align="left">enables deflate compression only, see Section&nbsp;<a href="#sec:compression">19.27</a> </td></tr>
<tr><td align="left"><i>WITH_FAST</i>	</td><td align="left">use faster memory allocation for <i>WITH_LEAN</i>/<i>WITH_LEANER</i> </td></tr>
<tr><td align="left"><i>WITH_NOIO</i>	</td><td align="left">eliminates need for file IO and BSD socket library, see Section&nbsp;<a href="#sec:noio">19.33</a> </td></tr>
<tr><td align="left"><i>WITH_NOIDREF</i>	</td><td align="left">eliminates href/ref and id attributes to (de)serialize multi-ref data,</td></tr>
<tr><td align="left"></td><td align="left">or alternatively use the <i>SOAP_XML_TREE</i> runtime flag </td></tr>
<tr><td align="left"><i>WITH_NOHTTP</i>	</td><td align="left">eliminates HTTP stack to reduce code size </td></tr>
<tr><td align="left"><i>WITH_NOZONE</i>	</td><td align="left">silently ignores the timezone in time conversions </td></tr>
<tr><td align="left"><i>WITH_LEAN</i>	</td><td align="left">creates a small-footprint executable, see Section&nbsp;<a href="#sec:lean">19.32</a> </td></tr>
<tr><td align="left"><i>WITH_LEANER</i>	</td><td align="left">creates an even smaller footprint executable, see Section&nbsp;<a href="#sec:lean">19.32</a> </td></tr>
<tr><td align="left"><i>WITH_COMPAT</i>	</td><td align="left">removes dependency on C++ stream libraries, eliminating C++ exceptions </td></tr>
<tr><td align="left"><i>WITH_NONAMESPACES</i></td><td align="left">removes dependence on global <i>namespaces</i> table, MUST set it </td></tr>
<tr><td align="left"></td><td align="left">explicitly with <i>soap_set_.namespaces()</i> </td></tr>
<tr><td align="left"></td><td align="left">see also Section&nbsp;<a href="#sec:nstable">10.4</a> </td></tr>
<tr><td align="left"><i>WITH_PURE_VIRTUAL</i>	</td><td align="left">for C++ abstract service classes with pure virtual methods </td></tr>
<tr><td align="left"><i>WITH_NOEMPTYSTRUCT</i>	</td><td align="left">inserts a dummy member in empty structs to allow compilation </td></tr>
<tr><td align="left"><i>WITH_NOGLOBAL</i>	</td><td align="left">omit SOAP Header and Fault serialization code </td></tr>
<tr><td align="left"><i>WITH_NOCDATA</i>	</td><td align="left">do not retain the parsed CDATA sections in literal XML strings (convert) </td></tr>
<tr><td align="left"><i>WITH_CDATA</i>	</td><td align="left">retain the parsed CDATA sections in literal XML strings (no conversion, default) </td></tr>
<tr><td align="left"><i>WITH_C_LOCALE</i>	</td><td align="left">use locale functions when available to ensure locale-independent </td></tr>
<tr><td align="left"></td><td align="left">number conversions (force the use of C locale) </td></tr>
<tr><td align="left"><i>WITH_CASEINSENSITIVETAGS</i>	</td><td align="left">enable case insensitive XML parsing </td></tr>
<tr><td align="left"><i>WITH_REPLACE_ILLEGAL_UTF8</i>	</td><td align="left">replaces UTF8 content that is outside the allowed range of XML 1.0 </td></tr></table>

</td></tr></table><br></span>
Other compile-time flags:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Macro</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left">SOCKET_CLOSE_ON_EXIT </td><td align="left">prevents a server port from staying in listening mode after exit </td></tr>
<tr><td align="left"></td><td align="left">by internally setting <i>fcntl(sock, F_SETFD, FD_CLOEXEC)</i> </td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
Compile-time flags to change the default engine settings:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Macro</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left">SOAP_BUFLEN </td><td align="left">the length of the internal message buffer (affects socket comms) </td></tr>
<tr><td align="left">SOAP_TAGLEN </td><td align="left">maximum length of XML tags and URL domain names (buffering) </td></tr>
<tr><td align="left">SOAP_SSL_RSA_BITS </td><td align="left">the length of the RSA key (2048 by default) </td></tr>
<tr><td align="left">SOAP_UNKNOWN_CHAR </td><td align="left">an 8 bit code that represents a character that could not be converted </td></tr>
<tr><td align="left"></td><td align="left">to an ASCII <i><b>char</b></i> (e.g.&nbsp;from Unicode, applicable when SOAP_C_UTFSTRING is off) </td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: it is important that all of these macros MUST be consistently defined to
compile all sources, such as <i>stdsoap2.cpp</i>, <i>soapC.cpp</i>,
<i>soapClient.cpp</i>, <i>soapServer.cpp</i>, and all application sources that
include <i>stdsoap2.h</i> or <i>soapH.h</i>. If the macros are not consistently
used, the application will crash due to a mismatches in the declaration and
access of the gSOAP context.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.12">
9.12</a>&nbsp;&nbsp;<font color="#0000FF">Run Time Flags</font></h3><a name="sec:flags">
</a>

<div class="p"><!----></div>
gSOAP provides flags to control the input and output mode settings at runtime.
These flags are divided into four categories: transport (IO), content encoding
(ENC), XML marshalling (XML), and C/C++ data mapping (C).

<div class="p"><!----></div>
Although gSOAP is fully SOAP 1.1 compliant, some SOAP implementations may have
trouble accepting multi-reference data and/or require explicit nil data so
these flags can be used to put gSOAP in "safe mode".  In addition, the
embedding (or inlining) of multi-reference data is adopted in the SOAP 1.2
specification, which gSOAP automatically supports when handling with SOAP 1.2
messages.

<div class="p"><!----></div>
To set and clear flags for inbound message processing use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i>soap_set_imode(soap, inflag);</i> <br />
<i>soap_clr_imode(soap, inflag);</i> <br />
</td></tr></table><br></span>
To set and clear the flags for outbound message processing use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i>soap_set_omode(soap, outflag);</i> <br />
<i>soap_clr_imode(soap, outflag);</i>
</td></tr></table><br></span>
To allocate and initialize a gSOAP context with inbound and outbound flags use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i>soap_new2(soap, inflag, outflag);</i>
</td></tr></table><br></span>
To initialize an unitialized gSOAP context with inbound and outbound flags use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i>soap_init2(soap, inflag, outflag);</i>
</td></tr></table><br></span>

<div class="p"><!----></div>
The input-mode and output-mode flags for inbound and outbound message processing are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Flag</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>SOAP_IO_FLUSH</i> </td><td align="left">in: disable buffering and flush output (default for all file-based output) </td></tr>
<tr><td align="left"><i>SOAP_IO_BUFFER</i> </td><td align="left">in: enable buffering (default for all socket-oriented connections) </td></tr>
<tr><td align="left"><i>SOAP_IO_STORE</i> </td><td align="left">in: store entire message to calculate HTTP content length </td></tr>
<tr><td align="left"><i>SOAP_IO_CHUNK</i> </td><td align="left">out: use HTTP chunking </td></tr>
<tr><td align="left"><i>SOAP_IO_LENGTH</i> </td><td align="left">out: (internal flag) require apriori calculation of content length </td></tr>
<tr><td align="left"><i>SOAP_IO_KEEPALIVE</i> </td><td align="left">in&amp;out: attempt to keep socket connections alive (open) </td></tr>
<tr><td align="left"><i>SOAP_IO_UDP</i> </td><td align="left">in&amp;out: use UDP (datagram) transport, maximum message length is <i>SOAP_BUFLEN</i> </td></tr>
<tr><td align="left"><i>SOAP_ENC_XML</i> </td><td align="left">out: use plain XML encoding without HTTP headers (useful with <i>SOAP_ENC_ZLIB</i>) </td></tr>
<tr><td align="left"><i>SOAP_ENC_DIME</i> </td><td align="left">out: use DIME encoding (automatic when DIME attachments are used) </td></tr>
<tr><td align="left"><i>SOAP_ENC_MIME</i> </td><td align="left">out: use MIME encoding (activate using <i>soap_set_mime</i>) </td></tr>
<tr><td align="left"><i>SOAP_ENC_MTOM</i> </td><td align="left">out: use MTOM XOP attachments (instead of DIME) </td></tr>
<tr><td align="left"><i>SOAP_ENC_ZLIB</i> </td><td align="left">out: compress encoding with Zlib (deflate or gzip format) </td></tr>
<tr><td align="left"><i>SOAP_ENC_SSL</i> </td><td align="left">in&amp;out: encrypt with SSL (automatic with "https:" endpoints) </td></tr>
<tr><td align="left"><i>SOAP_XML_INDENT</i> </td><td align="left">out: produces indented XML output </td></tr>
<tr><td align="left"><i>SOAP_XML_CANONICAL</i> </td><td align="left">out: produces canonical XML output </td></tr>
<tr><td align="left"><i>SOAP_XML_DEFAULTNS</i> </td><td align="left">out: produces xmlns="..." default binding namespaced output </td></tr>
<tr><td align="left"><i>SOAP_XML_IGNORENS</i> </td><td align="left">in: ignores the use of XML namespaces in input </td></tr>
<tr><td align="left"><i>SOAP_XML_STRICT</i> </td><td align="left">in: XML strict validation </td></tr>
<tr><td align="left"><i>SOAP_XML_TREE</i> </td><td align="left">out: serialize data as XML trees (no multi-ref, duplicate data when necessary) </td></tr>
<tr><td align="left"></td><td align="left">in: ignore id attributes (do not resolve id-ref) </td></tr>
<tr><td align="left"><i>SOAP_XML_GRAPH</i> </td><td align="left">out: serialize data as an XML graph with inline multi-ref (SOAP 1.2 default) </td></tr>
<tr><td align="left"><i>SOAP_XML_NIL</i> </td><td align="left">out: serialize NULL data as xsi:nil attributed elements </td></tr>
<tr><td align="left"><i>SOAP_XML_NOTYPE</i> </td><td align="left">out: disable <tt>xsi:type</tt> attributes </td></tr>
<tr><td align="left"><i>SOAP_C_NOIOB</i> </td><td align="left">in: do not fault with <i>SOAP_IOB</i> </td></tr>
<tr><td align="left"><i>SOAP_C_UTFSTRING</i> </td><td align="left">in&amp;out: (de)serialize 8-bit strings "as is" (strings MUST have UTF-8 encoded content) </td></tr>
<tr><td align="left"><i>SOAP_C_MBSTRING</i> </td><td align="left">in&amp;out: enable multibyte character support (depends on locale) </td></tr>
<tr><td align="left"><i>SOAP_C_NILSTRING</i> </td><td align="left">out: serialize empty strings as nil (ommited element) </td></tr></table>

</td></tr></table><br></span>
The flags can be selectively turned on/off at any time, for example when
multiple Web services are accessed by a client that require special treatment.

<div class="p"><!----></div>
All flags are orthogonal, except
<i>SOAP_IO_FLUSH</i>,
<i>SOAP_IO_BUFFER</i>,
<i>SOAP_IO_STORE</i>, and
<i>SOAP_IO_CHUNK</i>
which are enumerations and only one of these I/O flags can be used.  Also the
XML serialization flags
<i>SOAP_XML_TREE</i> and
<i>SOAP_XML_GRAPH</i> should not be mixed.

<div class="p"><!----></div>
The flags control the inbound and outbound message transport, encoding, and
(de)serialization.  The following functions are used to set and reset the flags
for input and output modes:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>soap_init2(<b>struct</b>&nbsp;soap *soap, int imode, int omode)</i> </td><td align="left">Initialize the runtime and set flags </td></tr>
<tr><td align="left"><i>soap_imode(<b>struct</b>&nbsp;soap *soap, int imode)</i> </td><td align="left">Set all input mode flags </td></tr>
<tr><td align="left"><i>soap_omode(<b>struct</b>&nbsp;soap *soap, int omode)</i> </td><td align="left">Set all output mode flags </td></tr>
<tr><td align="left"><i>soap_set_imode(<b>struct</b>&nbsp;soap *soap, int imode)</i> </td><td align="left">Enable input mode flags </td></tr>
<tr><td align="left"><i>soap_set_omode(<b>struct</b>&nbsp;soap *soap, int omode)</i> </td><td align="left">Enable output mode flags </td></tr>
<tr><td align="left"><i>soap_clr_imode(<b>struct</b>&nbsp;soap *soap, int omode)</i> </td><td align="left">Disable input mode flags </td></tr>
<tr><td align="left"><i>soap_clr_omode(<b>struct</b>&nbsp;soap *soap, int omode)</i> </td><td align="left">Disable output mode flags </td></tr></table>

</td></tr></table><br></span>
The default setting is <i>SOAP_IO_DEFAULT</i> for both input and output modes.

<div class="p"><!----></div>
For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init2(&amp;soap, SOAP_IO_KEEPALIVE, <br />
&nbsp;&nbsp;&nbsp;SOAP_IO_KEEPALIVE | SOAP_ENC_ZLIB | SOAP_XML_TREE | SOAP_XML_CANONICAL); <br />
<b>if</b>&nbsp;(soap_call_ns__myMethod(&amp;soap, ...)) <br />
...
</td></tr></table><br></i>
sends a compressed client request with keep-alive enabled and all data serialized as canonical XML trees.

<div class="p"><!----></div>
In many cases, setting the input mode will have no effect, especially with HTTP
transport because gSOAP will determine the optimal input buffering and the
encoding used for an inbound message. The flags that have an effect on
handling inbound messages are <i>SOAP_IO_KEEPALIVE</i>, <i>SOAP_ENC_SSL</i>
(but automatic when "https:" endpoints are used or <i>soap_ssl_accept</i>),
<i>SOAP_C_NOIOB</i>, <i>SOAP_C_UTFSTRING</i>, and <i>SOAP_C_MBSTRING</i>.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: The <i>SOAP_XML_TREE</i> serialization flag can be used to
improve interoperability with SOAP implementations that are not fully SOAP 1.1
compliant.  However, a tree serialization will duplicate data when necessary
and will crash the serializer for cyclic data structures.

<div class="p"><!----></div>
Additional run-time flags to control sockets. 

<div class="p"><!----></div>
Use the following selection of flags that are OS dependent to control sockets for send/sendto/recv/recvfrom operations:

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>socket_flags</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>MSG_NOSIGNAL</i> </td><td align="left">disables sigpipe (check your OS, this is not portable) </td></tr>
<tr><td align="left"><i>MSG_DONTROUTE</i> </td><td align="left">bypass routing, use direct interface </td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
Use the following selection of flags to set client-side socket connection flags (setsockopt):

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>connect_flags</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>SO_NOSIGPIPE</i> </td><td align="left">disables sigpipe (check your OS, this is not portable) </td></tr>
<tr><td align="left"><i>SO_DEBUG</i> </td><td align="left">turns on recording of debugging information in the underlying protocol modules </td></tr>
<tr><td align="left"><i>SO_BROADCAST</i> </td><td align="left">permits sending of broadcast messages (e.g. with UDP) when permitted </td></tr>
<tr><td align="left"><i>SO_LINGER</i> </td><td align="left">set <i>soap.linger_time</i> (set this value as needed) </td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
Use the following selection of flags to set server-side socket connection accept flags (setsockopt):

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>accept_flags</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>SO_NOSIGPIPE</i> </td><td align="left">disables sigpipe (check your OS, this is not portable) </td></tr>
<tr><td align="left"><i>SO_DEBUG</i> </td><td align="left">turns on recording of debugging information in the underlying protocol modules </td></tr>
<tr><td align="left"><i>SO_REUSEADDR</i> </td><td align="left">reuse bind address immediately (prevents bind reject) </td></tr>
<tr><td align="left"><i>SO_LINGER</i> </td><td align="left">set <i>soap.linger_time</i> (set this value as needed) </td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
For example, <i>soap.accept_flags = (SO_NOSIGPIPE  -  SO_LINGER)</i> disables sigpipe signals and set linger time value given by <i>soap.linger_time</i> (zero by default).

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.13">
9.13</a>&nbsp;&nbsp;<font color="#0000FF">Memory Management</font></h3><a name="sec:memory">
</a>

<div class="p"><!----></div>
Understanding gSOAP's run-time memory management is important to optimize
client and service applications by eliminating memory leaks and/or dangling
references.

<div class="p"><!----></div>
There are two forms of dynamic (heap) allocations made by gSOAP's runtime for
serialization and deserialization of data.  Temporary data is created by the
runtime such as hash tables to keep pointer reference information for
serialization and hash tables to keep XML id/href information for
multi-reference object deserialization.  Deserialized data is created upon
receiving SOAP messages.  This data is stored on the heap and requires several
calls to the <i>malloc</i> library function to allocate space for the data and
<i><b>new</b></i> to create class instances.  All such allocations are tracked by
gSOAP's runtime by linked lists for later deallocation.  The linked list for
<i>malloc</i> allocations uses some extra space in each <i>malloc</i>ed block to
form a chain of pointers through the <i>malloc</i>ed blocks.  A separate
<i>malloc</i>ed linked list is used to keep track of class instance allocations.

<div class="p"><!----></div>
If you want to preserve the deserialized data before deleting a soap context, you can assign management of the data and delegate responsibility of deletion to another soap context using <i>soap_delegate_deletion(<b>struct</b>&nbsp;soap *soap_from, <b>struct</b>&nbsp;soap *soap_to)</i>. This moves all deserialized and temporary data to the other soap context <i>soap_to</i>, which will delete its data and all the delegated data it is responsible for when you call <i>soap_destroy</i> and <i>soap_end</i>. This can be particularly useful for making client calls inside a server operation, i.e.&nbsp;a mixed server/client. The client call inside the server operation requires a new soap context, e.g.&nbsp;copied from the server's with <i>soap_copy</i>. Before destroying the client context with <i>soap_free</i>, the data can be delegated to the server's context with <i>soap_delegate_deletion</i>. See <i>samples/mashup/machupserver.c</i> code for an example.

<div class="p"><!----></div>
Note that gSOAP does not per se enforce a deallocation policy and the user can
adopt a deallocation policy that works best for a particular application.  As a
consequence, deserialized data is never deallocated by the gSOAP runtime unless
the user explicitly forces deallocation by calling functions to deallocate data
collectively or individually.

<div class="p"><!----></div>
The deallocation functions are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function Call</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>soap_destroy(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Remove all dynamically allocated C++ objects. </td></tr>
<tr><td align="left"></td><td align="left">must be called before <i>soap_end()</i> </td></tr>
<tr><td align="left"><i>soap_end(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Remove temporary data and deserialized data except </td></tr>
<tr><td align="left"></td><td align="left">class instances </td></tr>
<tr><td align="left"><i>soap_free_temp(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Instead of <i>soap_destroy</i> and <i>soap_end</i>: </td></tr>
<tr><td align="left"></td><td align="left">remove temporary data only </td></tr>
<tr><td align="left"><i>soap_dealloc(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*p)</i> </td><td align="left">Remove malloced data at <i>p</i>. When <i>p==NULL</i>: remove all </td></tr>
<tr><td align="left"></td><td align="left">dynamically allocated (deserialized) data except class instances </td></tr>
<tr><td align="left"><i>soap_delete(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*p)</i> </td><td align="left">Remove class instance at <i>p</i>. When <i>p==NULL</i>: remove all </td></tr>
<tr><td align="left"></td><td align="left">dynamically allocated (deserialized) class instances </td></tr>
<tr><td align="left"></td><td align="left">(this is identical to calling soap_destroy(<b>struct</b>&nbsp;soap *soap)) </td></tr>
<tr><td align="left"><i>soap_unlink(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*p)</i> </td><td align="left">Unlink data/object at <i>p</i> from gSOAP's deallocation chain </td></tr>
<tr><td align="left"></td><td align="left">so gSOAP won't deallocate it </td></tr>
<tr><td align="left"><i>soap_done(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Detach context (reset runtime context) </td></tr>
<tr><td align="left"><i>soap_free(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">Detach and free context (allocated with <i>soap_new</i>) </td></tr></table>

</td></tr></table><br></span>
Temporary data (i.e.&nbsp;the hash tables) are automatically removed with calls to
the <i>soap_free_temp</i> function which is also made by <i>soap_end</i> and
<i>soap_done</i> or when the next call to a stub or skeleton routine is made to
send a message or receive a message.  Deallocation of non-class based data is
straightforward: <i>soap_end</i> removes all dynamically allocated deserialized
data (data allocated with <i>soap_malloc</i>.  That is, when the client/service
application does not use any class instances that are (de)marshalled, but uses
structs, arrays, etc., then calling the <i>soap_end</i> function is safe to
remove all deserialized data.  The function can be called after processing the
deserialized data of a service operation call or after a number of service operation
calls have been made.  The function is also typically called after
<i>soap_serve</i>, when the service finished sending the response to a client
and the deserialized client request data can be removed.

<div class="p"><!----></div>
Individual data objects can be unlinked from the deallocation chain if
necessary, to prevent deallocation by the collective <i>soap_end</i> or
<i>soap_destroy</i> functions.

<div class="p"><!----></div>
	      <h4><a name="tth_sEc9.13.1">
9.13.1</a>&nbsp;&nbsp;<font color="#0000FF">Memory Allocation and Management Policies</font></h4>

<div class="p"><!----></div>
There are three situations to consider for memory deallocation policies for class instances:

<ol type="1">
<li> the program code deletes the class
instances and the class destructors in turn SHOULD delete and free any dynamically allocated data (deep deallocation) without
calling the <i>soap_end</i> and <i>soap_destroy</i> functions,
<div class="p"><!----></div>
</li>

<li> or the class
destructors SHOULD NOT deallocate any data and the <i>soap_end</i> and <i>soap_destroy</i> functions can be called to remove
the data.
<div class="p"><!----></div>
</li>

<li> or the class
destructors SHOULD mark their own deallocation and mark the deallocation of any other data deallocated by it's destructors
by calling the <i>soap_unlink</i> function. This allows
<i>soap_destroy</i> and <i>soap_end</i> to remove the remaining instances and data without causing duplicate deallocations.
<div class="p"><!----></div>
</li>
</ol>
It is advised to use pointers to class instances that are used within other structs and classes to avoid the creation of temporary
class instances during deserialization. The problem with temporary class instances is that the destructor of the temporary may affect data used by
other instances through the sharing of data parts accessed with pointers. Temporaries and even whole copies of class instances
can be created when deserializing SOAP multi-referenced objects.
A dynamic array of class instances is similar: temporaries may be created to fill the array upon deserialization. To avoid
problems, use dynamic arrays of pointers to class instances. This also enables the exchange of polymorphic arrays when the
elements are instances of classes in an inheritance hierarchy.
In addition, allocate data and class instances with <i>soap_malloc</i> and <i>soap_new_X</i> functions (more details below).

<div class="p"><!----></div>
To summarize, it is advised to pass class data types by pointer to a service operation. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;X { ... }; <br />
ns__remoteMethod(X *in, ...);
</td></tr></table><br></i>
Response elements that are class data types can be passed by reference, as in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;X { ... }; <br />
<b>class</b>&nbsp;ns__remoteMethodResponse { ... }; <br />
ns__remoteMethod(X *in, ns__remoteMethodResponse &amp;out);
</td></tr></table><br></i>
But dynamic arrays declared as class data types should use a pointer to a valid object that will be overwritten when the
function is called, as in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>int</b>&nbsp;xsd__int; <br />
<b>class</b>&nbsp;X { ... }; <br />
<b>class</b>&nbsp;ArrayOfint { xsd__int *__ptr; <b>int</b>&nbsp;__size; }; <br />
ns__remoteMethod(X *in, ArrayOfint *out);
</td></tr></table><br></i>
Or a reference to a valid or <i>NULL</i> pointer, as in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>int</b>&nbsp;xsd__int; <br />
<b>class</b>&nbsp;X { ... }; <br />
<b>class</b>&nbsp;ArrayOfint { xsd__int *__ptr; <b>int</b>&nbsp;__size; }; <br />
ns__remoteMethod(X *in, ArrayOfint *&amp;out);
</td></tr></table><br></i>
The gSOAP memory allocation functions can be used in client and/or service code to allocate temporary data that will be
automatically deallocated.
These functions are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function Call</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;*soap_malloc(<b>struct</b>&nbsp;soap *soap, size_t n)</i> </td><td align="left">return pointer to <i>n</i> bytes </td></tr>
<tr><td align="left"><i><u><span class="roman">Class</span></u> *soap_new_<u><span class="roman">Class</span></u>(<b>struct</b>&nbsp;soap *soap)</i> </td><td align="left">instantiate <u><span class="roman">Class</span></u> </td></tr>
<tr><td align="left"><i><u><span class="roman">Class</span></u> *soap_new_<u><span class="roman">Class</span></u>(<b>struct</b>&nbsp;soap *soap, <b>int</b>&nbsp;n)</i> </td><td align="left">instantiate array of <i>n</i> objects </td></tr>
<tr><td align="left"><i><u><span class="roman">Class</span></u> *soap_new_set_<u><span class="roman">Class</span></u>(<b>struct</b>&nbsp;soap *soap, m<sub>1</sub>, ..., m<sub>n</sub>)</i> </td><td align="left">instantiate and set members <i>m</i><sub>i</sub> </td></tr>
<tr><td align="left"><i><u><span class="roman">Class</span></u> *soap_new_req_<u><span class="roman">Class</span></u>(<b>struct</b>&nbsp;soap *soap, m<sub>1</sub>, ..., m<sub>n</sub>)</i> </td><td align="left">instantiate and set required-only <i>m</i><sub>i</sub> </td></tr></table>

</td></tr></table><br></span>
The <i>soap_new_X</i> functions are generated by the gSOAP <i>soapcpp2</i> compiler for every class <i>X</i> in the header file.

<div class="p"><!----></div>
Space allocated with <i>soap_malloc</i> will be released with the <i>soap_end</i> and <i>soap_dealloc</i> functions.
All objects instantiated with <i>soap_new_X(<b>struct</b>&nbsp;soap*)</i> are removed altogether with <i>soap_destroy(<b>struct</b>&nbsp;soap*)</i>.
To remove just a single object, use <i>soap_delete_X(<b>struct</b>&nbsp;soap*, X*)</i>.

<div class="p"><!----></div>
For example, the following service uses temporary data in the service operation implementation:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ ... <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_serve(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;... <br />
}
</td></tr></table><br></i>
An example service operation that allocates a temporary string is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__itoa(<b>struct</b>&nbsp;soap *soap, <b>int</b>&nbsp;i, <b>char</b>&nbsp;**a) <br />
{ <br />
&nbsp;&nbsp;&nbsp;*a = (char*)soap_malloc(soap, 11); <br />
&nbsp;&nbsp;&nbsp;sprintf(*a, "%d", i); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
This temporary allocation can also be used to allocate strings for the SOAP Fault data structure. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__mymethod(...) <br />
{ ... <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(exception) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*msg = (<b>char</b>*)soap_malloc(soap, 1024); // allocate temporary space for detailed message <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sprintf(msg, "...", ...); // produce the detailed message <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_receiver_fault(soap, "An exception occurred", msg); // return the server-side fault <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;... <br />
}
</td></tr></table><br></i>
Use <i>soap_receiver_fault(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*faultstring, <b>const</b>&nbsp;<b>char</b>&nbsp;*detail)</i> to set a SOAP 1.1/1.2 fault at the server-side.
Use <i>soap_sender_fault(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*faultstring,
<b>const</b>&nbsp;<b>char</b>&nbsp;*detail)</i> to set a SOAP 1.1/1.2 unrecoverable Bad Request fault
at the server-side. Sending clients are not supposed to retry messages after a
Bad Request, while errors at the receiver-side indicate temporary problems.

<div class="p"><!----></div>
The above functions do not include a SOAP 1.2 Subcode element. To include Subcode element, use <i>soap_receiver_fault_subcode(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*subcode, <b>const</b>&nbsp;<b>char</b>&nbsp;*faultstring, <b>const</b>&nbsp;<b>char</b>&nbsp;*detail)</i> to set a SOAP 1.1/1.2 fault with Subcode at the server-side.
Use <i>soap_sender_fault_subcode(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*subcode, <b>const</b>&nbsp;<b>char</b>&nbsp;*faultstring, <b>const</b>&nbsp;<b>char</b>&nbsp;*detail)</i> to set a SOAP 1.1/1.2 unrecoverable Bad Request fault with Subcode at the server-side.

<div class="p"><!----></div>
gSOAP provides a function to duplicate a string into gSOAP's memory space:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i><b>char</b>&nbsp;*soap_strdup(<b>struct</b>&nbsp;soap *soap, const char *s)</i>
</td></tr></table><br></span>
The function allocates space for <i>s</i> with <i>soap_malloc</i>, copies the
string, and returns a pointer to the duplicated string. When <i>s</i> is NULL,
the function does not allocate and copy the string and returns NULL.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc9.13.2">
9.13.2</a>&nbsp;&nbsp;<font color="#0000FF">Intra-Class Memory Management</font></h4><a name="sec:classmemory">
</a>

<div class="p"><!----></div>
When a class declaration has a <i><b>struct</b>&nbsp;soap *</i> field, this field will be set to point to the current gSOAP runtime context by
gSOAP's deserializers and by the <i>soap_new_Class</i> functions.
This simplifies memory management for class instances.
The <i><b>struct</b>&nbsp;soap*</i> pointer is implicitly set by the gSOAP deserializer for
the class or explicitly by calling the <i>soap_new_X</i> function for class <i>X</i>.
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;Sample <br />
{ <b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap *soap; // reference to gSOAP's run-time <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;Sample(); <br />
&nbsp;&nbsp;&nbsp;~Sample(); <br />
};
</td></tr></table><br></i>
The constructor and destructor for class <i>Sample</i> are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
Sample::Sample() <br />
{ this<tt>-&gt;</tt>soap = NULL; <br />
} <br />
Sample::~Sample() <br />
{ soap_unlink(this<tt>-&gt;</tt>soap, this); <br />
}
</td></tr></table><br></i>
The <i>soap_unlink()</i> call removes the object from gSOAP's deallocation chain.
In that way, <i>soap_destroy</i> can be safely called to remove all class instances.
The following code illustrates the explicit creation of a <i>Sample</i> object and cleanup:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap *soap = soap_new(); // new gSOAP runtime <br />
Sample *obj = soap_new_Sample(soap); // new Sample object with obj<tt>-&gt;</tt>soap set to runtime <br />
... <br />
<b>delete</b>&nbsp;obj; // also calls soap_unlink to remove obj from the deallocation chain <br />
soap_destroy(soap); // deallocate all (other) class instances <br />
soap_end(soap); // clean up
</td></tr></table><br></i>
Here is another example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;ns__myClass <br />
{ ... <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap *soap; // set by soap_new_ns__myClass() <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;<b>void</b>&nbsp;setName(<b>const</b>&nbsp;<b>char</b>&nbsp;*s); <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
Calls to <i>soap_new_ns__myClass(soap)</i> will set the <i>soap</i> field in the class instance to the current gSOAP
context. Because the deserializers invoke the <i>soap_new</i> functions, the <i>soap</i> field of the <i>ns__myClass</i>
instances are set as well.
This mechanism is convenient when Web Service methods need to return objects that are instantiated in the methods.
For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__myMethod(<b>struct</b>&nbsp;soap *soap, ...) <br />
{ <br />
&nbsp;&nbsp;&nbsp;ns__myClass *p = soap_new_ns__myClass(soap); <br />
&nbsp;&nbsp;&nbsp;p<tt>-&gt;</tt>setName("SOAP"); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
<b>void</b>&nbsp;ns__myClass::ns__setName(<b>const</b>&nbsp;<b>char</b>&nbsp;*s) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name = (<b>char</b>*)soap_malloc(soap, strlen(s)+1); <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name = (<b>char</b>*)malloc(strlen(s)+1); <br />
&nbsp;&nbsp;&nbsp;strcpy(name, s); <br />
} <br />
ns__myClass::ns__myClass() <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap = NULL; <br />
&nbsp;&nbsp;&nbsp;name = NULL; <br />
} <br />
ns__myClass::~ns__myClass() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap &amp;&amp; name) free(name); <br />
&nbsp;&nbsp;&nbsp;soap_unlink(soap, this); <br />
} 
</td></tr></table><br></i>
Calling <i>soap_destroy</i> right after <i>soap_serve</i> in the Web Service will destroy all dynamically allocated
class instances.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.14">
9.14</a>&nbsp;&nbsp;<font color="#0000FF">Debugging</font></h3>

<div class="p"><!----></div>
To activate debugging and message logging, set the <i>#define DEBUG</i> macro
on the compiler's command line (typically as a compiler option <i>-DDEBUG</i>)
or in <i>stdsoap2.h</i>, and recompile your code together with <i>stdsoap2.c</i>
or <i>stdsoap2.cpp</i> (instead of <i>libgsoap</i>). When using
<i>libgsoap</i> and <i>libgsoap++</i>, reinstall the software with
<i>\.configure</i> using option <i>-enable-debug</i>.

<div class="p"><!----></div>
When your client and server applications run, they will log their activity in three
separate files:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>File</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left"><i>SENT.log</i> </td><td align="left">The SOAP content transmitted by the application </td></tr>
<tr><td align="left"><i>RECV.log</i> </td><td align="left">The SOAP content received by the application </td></tr>
<tr><td align="left"><i>TEST.log</i> </td><td align="left">A log containing various activities performed by the application </td></tr></table>

</td></tr></table><br></span>
<font color="#FF0000"><b>Caution</b></font>: The client and server applications may run slow due to the logging activity.

<div class="p"><!----></div>
<font color="#FF0000"><b>Hint</b></font>: Set macro <i>DEBUG_STAMP</i> instead of <i>DEBUG</i> to add time
stamps to <i>TEST.log</i>. This works on platforms supporting the
<i>gettimeofday</i> function.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: When installing a CGI application on the Web with debugging activated, the log files may sometimes not be created due to file
access permission restrictions imposed on CGI applications. To get around this, create empty log files with universal write
permissions. Be careful about the security implication of this.

<div class="p"><!----></div>
You can test a service CGI application without deploying it on the Web.
To do this, create a client application for the service and activate message logging by this client.
Remove any old <i>SENT.log</i> file and run the client (which connects to the Web service or to another dummy, but valid address)
and copy the <i>SENT.log</i> file to another file, e.g. <i>SENT.tst</i>.
Then redirect the <i>SENT.tst</i> file to the service CGI application.  For example,
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  ./myservice.cgi</i>  &lt;  <i>SENT.tst</i>
</td></tr></table><br></span>
This should display the service response on the terminal.

<div class="p"><!----></div>
The file names of the log files and the logging activity can be controlled at the application level. This allows the creation of
separate log files by separate services, clients, and threads.
For example, the following service logs all SOAP messages (but no debug messages) in separate directories:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
... <br />
soap_set_recv_logfile(&amp;soap, "logs/recv/service12.log"); // append all messages received in /logs/recv/service12.log <br />
soap_set_sent_logfile(&amp;soap, "logs/sent/service12.log"); // append all messages sent in /logs/sent/service12.log <br />
soap_set_test_logfile(&amp;soap, NULL); // no file name: do not save debug messages <br />
... <br />
soap_serve(&amp;soap); <br />
...
</td></tr></table><br></i>
Likewise, messages can be logged for individual client-side service operation calls.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.15">
9.15</a>&nbsp;&nbsp;<font color="#0000FF">Generating an Auto Test Server for Client Testing</font></h3>

<div class="p"><!----></div>
The <i>soapcpp2 -T</i> option generates an auto-test server application in <i>soapTester.cpp</i>, which is to be compiled and linked with the code generated for a server implementation, i.e.&nbsp;<i>soapServer.cpp</i> (or with the generated server object class) and <i>soapC.cpp</i>. The feature also supports C, so use the <i>soapcpp2 -c</i> option to generate C.

<div class="p"><!----></div>
The auto-test server can be used to test a client application. Suppose the
generated code is compiled into the executable named <i>tester</i> (compile <i>soapServer.cpp</i>, <i>soapC.cpp</i>, and <i>stdsoap2.cpp</i> or link <i>libgsoap++</i>). We can use the IO
redirect to "send" it a message saved in a file, for example one of the
sample request messages generated by <i>soapcpp2</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
 &gt;  ./tester  &lt;  example.req.xml
</td></tr></table><br></span>
which then returns the response with default XML values displayed on the terminal.

<div class="p"><!----></div>
To run the auto test service on a port to test a client against, use two command-line arguments. The first argument is the OR-ed values of the gSOAP runtime context flags such as <i>SOAP_IO_KEEPALIVE</i> (0x10 = 16) and the second argument is the port number:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
 &gt;  ./tester 16 8080
</td></tr></table><br></span>
This starts an iterative stand-alone server on port 8080. This way, messages
can be sent to <tt>http://localhost:8080</tt> to test the client. The data in the
response messages are copied from the request messages
when possible, or XML default values, or empty otherwise.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc9.16">
9.16</a>&nbsp;&nbsp;<font color="#0000FF">Required Libraries</font></h3>

<div class="p"><!----></div>

<ul>
<li> The socket library is essential and requires the inclusion of the appropriate libraries with the compile command for Sun
Solaris systems:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -o myclient myclient.cpp stdsoap2.cpp soapC.cpp soapClient.cpp -lsocket -lxnet -lnsl</i>
</td></tr></table><br></span>
These library loading options are not required with Linux.
<div class="p"><!----></div>
</li>

<li> The gSOAP runtime uses the math library for the <tt>NaN</tt>, <tt>INF</tt>, and <tt>-INF</tt> floating point representations.  The library
is not strictly necessary and the <i> &lt; math.h &gt; </i> header file import can be commented out from the <i>stdsoap2.h</i> header file.
The application can be linked without the <i>-lm</i> math library e.g. under Sun Solaris:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -o myclient myclient.cpp stdsoap2.cpp soapC.cpp soapClient.cpp -lsocket -lxnet -lnsl</i>
</td></tr></table><br></span>
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
 <h2><a name="tth_sEc10">
10</a>&nbsp;&nbsp;<font color="#0000FF">The gSOAP Service Operation Specification Format</font></h2>

<div class="p"><!----></div>
A service operation is specified as a C/C++ function prototype in a header
file. The function is REQUIRED to return <i><b>int</b></i>, which is used to represent
a SOAP error code, see Section&nbsp;<a href="#sec:errcodes">10.2</a>. Multiple service operations MAY
be declared together in one header file.

<div class="p"><!----></div>
The general format of a service operation specification is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<font size="+1"><span class="roman">[</span></font><b>int</b><font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font>namespace_prefix__<font size="+1"><span class="roman">]</span></font>method_name(<font size="+1"><span class="roman">[</span></font>inparam1, inparam2, ...,<font size="+1"><span class="roman">]</span></font> outparam);
</td></tr></table><br></i>
where

<dl compact="compact">
 <dt><b><span class="roman"><i>namespace_prefix__</i></b></dt>
	<dd> is the optional namespace prefix of the method (see identifier translation rules&nbsp;<a href="#sec:idtrans">10.3</a>)</span></dd>
 <dt><b><span class="roman"><i>method_name</i></b></dt>
	<dd>	 it the service operation name (see identifier translation rules&nbsp;<a href="#sec:idtrans">10.3</a>)</span></dd>
 <dt><b><span class="roman"><i>inparam</i></b></dt>
	<dd>		 is the declaration of an input parameter of the service operation</span></dd>
 <dt><b><span class="roman"><i>outparam</i></b></dt>
	<dd>	 is the declaration of the output parameter of the service operation</span></dd>
</dl>
This simple form can only pass a single, non-<i><b>struct</b></i> and non-<i><b>class</b></i>
type output parameter. See&nbsp;<a href="#sec:param">10.1</a> for passing multiple output
parameters. The name of the declared function <i>namespace_prefix__
method_name</i> must be unique and cannot match the name of a <i><b>struct</b></i>,
<i><b>class</b></i>, or <i><b>enum</b></i> declared in the same header file.

<div class="p"><!----></div>
The method request is encoded in SOAP as an XML element and the namespace prefix, method name, and input parameters are encoded using the format:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>method_name xsi:type="<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>method_name&#62; <br />
&lt;inparam-name1 xsi:type="..."&#62;...&lt;/inparam-name1&#62; <br />
&lt;inparam-name2 xsi:type="..."&#62;...&lt;/inparam-name2&#62; <br />
... <br />
&lt;/<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>method_name&#62;
</td></tr></table><br></tt>
where the <tt>inparam-name</tt> accessors are the element-name representations of the <i>inparam</i> parameter name declarations, see
Section&nbsp;<a href="#sec:idtrans">10.3</a>. (The optional parts are shown enclosed in <font size="+1"><span class="roman">[</span></font><font size="+1"><span class="roman">]</span></font>.)

<div class="p"><!----></div>
The XML response by the Web service is of the form:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>method-nameResponse xsi:type="<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>method-nameResponse&#62; <br />
&lt;outparam-name xsi:type="..."&#62;...&lt;/outparam-name&#62; <br />
&lt;/<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>method-nameResponse&#62;
</td></tr></table><br></tt>
where the <tt>outparam-name</tt> accessor is the element-name representation of the <i>outparam</i> parameter name declaration, see
Section&nbsp;<a href="#sec:idtrans">10.3</a>. By convention, the response element name is the method name ending in <tt>Response</tt>.
See&nbsp;<a href="#sec:param">10.1</a> on how to change the declaration if the service response element name is different.

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> tool generates a stub routine for the service
operation. This stub is of the form:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;soap_call_<font size="+1"><span class="roman">[</span></font>namespace_prefix__<font size="+1"><span class="roman">]</span></font>method_name(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*URL, <b>char</b>&nbsp;*action, <font size="+1"><span class="roman">[</span></font>inparam1, inparam2, ...,<font size="+1"><span class="roman">]</span></font> outparam);
</td></tr></table><br></i>
This proxy can be called by a client application to perform the service operation
call.

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> tool generates a skeleton routine for the
service operation. The skeleton function is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;soap_serve_<font size="+1"><span class="roman">[</span></font>namespace_prefix__<font size="+1"><span class="roman">]</span></font>method_name(<b>struct</b>&nbsp;soap *soap);
</td></tr></table><br></i>
The skeleton routine, when called by a service application, will attempt to
serve a request on the standard input. If no request is present or if the
request does not match the method name, <i>SOAP_NO_METHOD</i> is returned.
The skeleton routines are automatically called by the generated
<i>soap_serve</i> routine that handles all requests.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc10.1">
10.1</a>&nbsp;&nbsp;<font color="#0000FF">Service Operation Parameter Passing</font></h3><a name="sec:param">
</a>

<div class="p"><!----></div>
The input parameters of a service operation MUST be passed by value.  Input
parameters cannot be passed by reference with the <i>&amp;</i> reference operator,
but an input parameter value MAY be passed by a pointer to the data.  Of
course, passing a pointer to the data is preferred when the size of the data of
the parameter is large.  Also, to pass instances of (derived) classes, pointers
to the instance need to be used to avoid passing the instance by value which
requires a temporary and prohibits passing derived class instances.  When two
input parameter values are identical, passing them using a pointer has the
advantage that the value will be encoded only once as multi-reference (hence,
the parameters are aliases).  When input parameters are passed using a pointer,
the data pointed to will not be modified by the service operation and returned to
the caller.

<div class="p"><!----></div>
The output parameter MUST be passed by reference using <i>&amp;</i> or by using a
pointer. Arrays are passed by reference by default and do not require the use
of the reference operator <i>&amp;</i>.

<div class="p"><!----></div>
The input and output parameter types have certain limitations, see
Section&nbsp;<a href="#sec:limitations">9.10</a>

<div class="p"><!----></div>
If the output parameter is a <i><b>struct</b></i> or <i><b>class</b></i> type, it is
considered a service operation response element instead of a simple output
parameter value. That is, the name of the <i><b>struct</b></i> or <i><b>class</b></i> is the
name of the response element and the <i><b>struct</b></i> or <i><b>class</b></i> fields are
the output parameters of the service operation, see also&nbsp;<a href="#sec:response">7.1.7</a>. Hence,
if the output parameter has to be a <i><b>struct</b></i> or <i><b>class</b></i>, a response
<i><b>struct</b></i> or <i><b>class</b></i> MUST be declared as well.  In addition, if a
service operation returns multiple output parameters, a response <i><b>struct</b></i> or
<i><b>class</b></i> MUST be declared. By convention, the response element is the
service operation name ending with "<tt>Response</tt>".

<div class="p"><!----></div>
The general form of a response element declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;<font size="+1"><span class="roman">[</span></font>namespace_prefix__<font size="+1"><span class="roman">]</span></font>response_element_name <br />
{ <br />
&nbsp;&nbsp;&nbsp;outparam1; <br />
&nbsp;&nbsp;&nbsp;outparam2; <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
where

<dl compact="compact">
 <dt><b><span class="roman"><i>namespace_prefix__</i></b></dt>
	<dd> is the optional namespace prefix of the response element (see identifier translation rules&nbsp;<a href="#sec:idtrans">10.3</a>)</span></dd>
 <dt><b><span class="roman"><i>response_element_name</i></b></dt>
	<dd>	 it the name of the response element (see identifier translation rules&nbsp;<a href="#sec:idtrans">10.3</a>)</span></dd>
 <dt><b><span class="roman"><i>outparam</i></b></dt>
	<dd>	 is the declaration of an output parameter of the service operation</span></dd>
</dl>
The general form of a service operation specification with a response element declaration for (multiple) output parameters is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<font size="+1"><span class="roman">[</span></font><b>int</b><font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font>namespace_prefix__<font size="+1"><span class="roman">]</span></font>method_name(<font size="+1"><span class="roman">[</span></font>inparam1, inparam2, ...,<font size="+1"><span class="roman">]</span></font> <b>struct</b>&nbsp;<font size="+1"><span class="roman">[</span></font>namespace_prefix__<font size="+1"><span class="roman">]</span></font>response_element_name {outparam1<font size="+1"><span class="roman">[</span></font>, outparam2, ...<font size="+1"><span class="roman">]</span></font>} &amp;anyparam);
</td></tr></table><br></i>
The choice of name for <i>anyparam</i> has no effect on the SOAP encoding and decoding and is only used as a place holder for the
response.

<div class="p"><!----></div>
The method request is encoded in SOAP as an independent element and the
namespace prefix, method name, and input parameters are encoded using the
format:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>method-name xsi:type="<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>method-name&#62; <br />
&lt;inparam-name1 xsi:type="..."&#62;...&lt;/inparam-name1&#62; <br />
&lt;inparam-name2 xsi:type="..."&#62;...&lt;/inparam-name2&#62; <br />
... <br />
&lt;/<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>method-name&#62;
</td></tr></table><br></tt>
where the <tt>inparam-name</tt> accessors are the element-name representations of
the <i>inparam</i> parameter name declarations, see Section&nbsp;<a href="#sec:idtrans">10.3</a>.
(The optional parts resulting from the specification are shown enclosed in
<font size="+1"><span class="roman">[</span></font><font size="+1"><span class="roman">]</span></font>.)

<div class="p"><!----></div>
The method response is expected to be of the form:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>response-element-name xsi:type="<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>response-element-name&#62; <br />
&lt;outparam-name1 xsi:type="..."&#62;...&lt;/outparam-name1&#62; <br />
&lt;outparam-name2 xsi:type="..."&#62;...&lt;/outparam-name2&#62; <br />
... <br />
&lt;/<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>response-element-name&#62;
</td></tr></table><br></tt>
where the <tt>outparam-name</tt> accessors are the element-name representations of
the <i>outparam</i> parameter name declarations, see Section&nbsp;<a href="#sec:idtrans">10.3</a>.
(The optional parts resulting from the specification are shown enclosed in
<font size="+1"><span class="roman">[</span></font><font size="+1"><span class="roman">]</span></font>.)

<div class="p"><!----></div>
The input and/or output parameters can be made anonymous, which allows the
deserialization of requests/responses with different parameter names as is
endorsed by the SOAP 1.1 specification, see Section&nbsp;<a href="#sec:anonymous">7.1.13</a>.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc10.2">
10.2</a>&nbsp;&nbsp;<font color="#0000FF">Error Codes</font></h3><a name="sec:errcodes">
</a>

<div class="p"><!----></div>
The error codes returned by the stub and skeleton routines are listed below.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="right"><font color="#FF0000"><b>Code</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="right"><i>SOAP_OK</i> </td><td align="left">No error </td></tr>
<tr><td align="right"><i>SOAP_CLI_FAULT</i>* </td><td align="left">The service returned a client fault (SOAP 1.2 Sender fault)</td></tr>
<tr><td align="right"><i>SOAP_SVR_FAULT</i>* </td><td align="left">The service returned a server fault (SOAP 1.2 Receiver fault)</td></tr>
<tr><td align="right"><i>SOAP_TAG_MISMATCH</i> </td><td align="left">An XML element didn't correspond to anything expected </td></tr>
<tr><td align="right"><i>SOAP_TYPE</i> </td><td align="left">An XML Schema type mismatch </td></tr>
<tr><td align="right"><i>SOAP_SYNTAX_ERROR</i> </td><td align="left">An XML syntax error occurred on the input </td></tr>
<tr><td align="right"><i>SOAP_NO_TAG</i> </td><td align="left">Begin of an element expected, but not found </td></tr>
<tr><td align="right"><i>SOAP_IOB</i> </td><td align="left">Array index out of bounds </td></tr>
<tr><td align="right"><i>SOAP_MUSTUNDERSTAND</i>* </td><td align="left">An element needs to be ignored that need to be understood </td></tr>
<tr><td align="right"><i>SOAP_NAMESPACE</i> </td><td align="left">Namespace name mismatch (validation error) </td></tr>
<tr><td align="right"><i>SOAP_FATAL_ERROR</i> </td><td align="left">Internal error </td></tr>
<tr><td align="right"><i>SOAP_USER_ERROR</i> </td><td align="left">User error (reserved for <i>soap.user</i> usage </td></tr>
<tr><td align="right"><i>SOAP_FAULT</i> </td><td align="left">An exception raised by the service </td></tr>
<tr><td align="right"><i>SOAP_NO_METHOD</i> </td><td align="left">The dispatcher did not find a matching operation for a request</td></tr>
<tr><td align="right"><i>SOAP_NO_DATA</i> </td><td align="left">No data in HTTP message </td></tr>
<tr><td align="right"><i>SOAP_GET_METHOD</i> </td><td align="left">HTTP GET operation not handled, see Section&nbsp;<a href="#sec:get">19.10</a> </td></tr>
<tr><td align="right"><i>SOAP_EOM</i> </td><td align="left">Out of memory </td></tr>
<tr><td align="right"><i>SOAP_MOE</i> </td><td align="left">Memory overflow/corruption error (DEBUG mode) </td></tr>
<tr><td align="right"><i>SOAP_NULL</i> </td><td align="left">An element was null, while it is not supposed to be null </td></tr>
<tr><td align="right"><i>SOAP_DUPLICATE_ID</i> </td><td align="left">Element's ID duplicated (multi-ref encoding) </td></tr>
<tr><td align="right"><i>SOAP_MISSING_ID</i> </td><td align="left">Element ID missing for an href/ref (multi-ref encoding) </td></tr>
<tr><td align="right"><i>SOAP_HREF</i> </td><td align="left">Reference to object is incompatible with the object refered to </td></tr>
<tr><td align="right"><i>SOAP_UTF_ERROR</i> </td><td align="left">An UTF-encoded message decoding error occured </td></tr>
<tr><td align="right"><i>SOAP_UDP_ERROR</i> </td><td align="left">Message too large to store in UDP packet </td></tr>
<tr><td align="right"><i>SOAP_TCP_ERROR</i> </td><td align="left">A connection error occured </td></tr>
<tr><td align="right"><i>SOAP_HTTP_ERROR</i> </td><td align="left">An HTTP error occured </td></tr>
<tr><td align="right"><i>SOAP_NTLM_ERROR</i> </td><td align="left">An NTLM authentication handshake error occured </td></tr>
<tr><td align="right"><i>SOAP_SSL_ERROR</i> </td><td align="left">An SSL error occured </td></tr>
<tr><td align="right"><i>SOAP_ZLIB_ERROR</i> </td><td align="left">A Zlib error occured </td></tr>
<tr><td align="right"><i>SOAP_PLUGIN_ERROR</i> </td><td align="left">Failed to register plugin </td></tr>
<tr><td align="right"><i>SOAP_MIME_ERROR</i> </td><td align="left">MIME parsing error </td></tr>
<tr><td align="right"><i>SOAP_MIME_HREF</i> </td><td align="left">MIME attachment has no href from SOAP body error </td></tr>
<tr><td align="right"><i>SOAP_MIME_END</i> </td><td align="left">End of MIME attachments protocol error </td></tr>
<tr><td align="right"><i>SOAP_DIME_ERROR</i> </td><td align="left">DIME formatting error or DIME size exceeds SOAP_MAXDIMESIZE </td></tr>
<tr><td align="right"><i>SOAP_DIME_END</i> </td><td align="left">End of DIME attachments protocol error </td></tr>
<tr><td align="right"><i>SOAP_DIME_HREF</i> </td><td align="left">DIME attachment has no href from SOAP body </td></tr>
<tr><td align="right"></td><td align="left">(and no DIME callbacks were defined to save the attachment) </td></tr>
<tr><td align="right"><i>SOAP_DIME_MISMATCH</i> </td><td align="left">DIME version/transmission error </td></tr>
<tr><td align="right"><i>SOAP_VERSIONMISMATCH</i>* </td><td align="left">SOAP version mismatch or no SOAP message </td></tr>
<tr><td align="right"><i>SOAP_DATAENCODINGUNKNOWN</i> </td><td align="left">SOAP 1.2 DataEncodingUnknown fault </td></tr>
<tr><td align="right"><i>SOAP_REQUIRED</i> </td><td align="left">Attributed required validation error </td></tr>
<tr><td align="right"><i>SOAP_PROHIBITED</i> </td><td align="left">Attributed prohibited validation error </td></tr>
<tr><td align="right"><i>SOAP_OCCURS</i> </td><td align="left">Element minOccurs/maxOccurs validation error </td></tr>
<tr><td align="right"><i>SOAP_LENGTH</i> </td><td align="left">Element length validation error </td></tr>
<tr><td align="right"><i>SOAP_FD_EXCEEDED</i> </td><td align="left">Too many open sockets </td></tr>
<tr><td align="right"></td><td align="left">(for non-win32 systems not supporting poll()) </td></tr>
<tr><td align="right"><i>SOAP_EOF</i> </td><td align="left">Unexpected end of file, no input, or timeout receiving data </td></tr>
<tr><td align="right"><i>SOAP_ERR</i> </td><td align="left">Error (for internal use) </td></tr></table>

</td></tr></table><br></span>
The error codes that are returned by a stub routine (proxy) upon receiving a
SOAP Fault from the server are marked (*).  The remaining error codes are
generated by the proxy itself as a result of problems with a SOAP payload.  The
error code is <i>SOAP_OK</i> when the service operation call was successful (the
<i>SOAP_OK</i> predefined constant is guaranteed to be <i>0</i>).  The error
code is also stored in <i>soap.error</i>, where <i>soap</i> is a variable that
contains the current runtime context. The function
<i>soap_print_fault(<b>struct</b>&nbsp;soap *soap, FILE *fd)</i> can be called to
display an error message on <i>fd</i> where current value of the
<i>soap.error</i> variable is used by the function to display the error.  The
function <i>soap_print_fault_location(<b>struct</b>&nbsp;soap *soap, FILE *fd)</i>
prints the location of the error if the error is a result from parsing XML.
Use <i>soap_sprint_fault(<b>struct</b>&nbsp;soap*, <b>char</b>&nbsp;*buf, size_t len)</i> to print the error to a string.

<div class="p"><!----></div>
A service operation implemented in a SOAP service MUST return an error code as the
function's return value. <i>SOAP_OK</i> denotes success and <i>SOAP_FAULT</i>
denotes an exception. The exception details can be assigned with the
<i>soap_receiver_fault(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*faultstring,
<b>const</b>&nbsp;<b>char</b>&nbsp;*detail)</i> which sets the strings
<i>soap.fault</i><tt>-&gt;</tt><i>faultstring</i> and
<i>soap.fault</i><tt>-&gt;</tt><i>detail</i> for SOAP 1.1, and
<i>soap.fault</i><tt>-&gt;</tt><i>SOAP_ENV__Reason</i> and
<i>soap.fault</i><tt>-&gt;</tt><i>SOAP_ENV__Detail</i> for SOAP 1.2, where
<i>soap</i> is a variable that contains the current runtime context, see
Section&nbsp;<a href="#sec:fault">12</a>.
A receiver error indicates that the service can't handle the request, but can possibly recover from the error.
To return an unrecoverable SOAP 1.1/1.2 error, use <i>soap_sender_fault(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*faultstring, <b>const</b>&nbsp;<b>char</b>&nbsp;*detail)</i>.

<div class="p"><!----></div>
To return a HTTP error code a service method can simply return the HTTP error code number.
For example, <i><b>return</b>&nbsp;404;</i> returns a "404 Not Found" HTTP error back to the client.  The <i>soap.error</i>
is set to the HTTP error code at the client side.
The HTTP 1.1 error codes are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="right"><font color="#FF0000"><b>#</b></font> </td><td align="left"><font color="#FF0000"><b>Error</b></font> </td></tr>
<tr><td align="right">201 </td><td align="left">Created </td></tr>
<tr><td align="right">202 </td><td align="left">Accepted </td></tr>
<tr><td align="right">203 </td><td align="left">Non-Authoritative Information </td></tr>
<tr><td align="right">204 </td><td align="left">No Content </td></tr>
<tr><td align="right">205 </td><td align="left">Reset Content </td></tr>
<tr><td align="right">206 </td><td align="left">Partial Content </td></tr>
<tr><td align="right">300 </td><td align="left">Multiple Choices </td></tr>
<tr><td align="right">301 </td><td align="left">Moved Permanently </td></tr>
<tr><td align="right">302 </td><td align="left">Found </td></tr>
<tr><td align="right">303 </td><td align="left">See Other </td></tr>
<tr><td align="right">304 </td><td align="left">Not Modified </td></tr>
<tr><td align="right">305 </td><td align="left">Use Proxy </td></tr>
<tr><td align="right">307 </td><td align="left">Temporary Redirect </td></tr>
<tr><td align="right">400 </td><td align="left">Bad Request </td></tr>
<tr><td align="right">401 </td><td align="left">Unauthorized </td></tr>
<tr><td align="right">402 </td><td align="left">Payment Required </td></tr>
<tr><td align="right">403 </td><td align="left">Forbidden </td></tr>
<tr><td align="right">404 </td><td align="left">Not Found </td></tr>
<tr><td align="right">405 </td><td align="left">Method Not Allowed </td></tr>
<tr><td align="right">406 </td><td align="left">Not Acceptable </td></tr>
<tr><td align="right">407 </td><td align="left">Proxy Authentication Required </td></tr>
<tr><td align="right">408 </td><td align="left">Request Time-out </td></tr>
<tr><td align="right">409 </td><td align="left">Conflict </td></tr>
<tr><td align="right">410 </td><td align="left">Gone </td></tr>
<tr><td align="right">411 </td><td align="left">Length Required </td></tr>
<tr><td align="right">412 </td><td align="left">Precondition Failed </td></tr>
<tr><td align="right">413 </td><td align="left">Request Entity Too Large </td></tr>
<tr><td align="right">414 </td><td align="left">Request-URI Too Large </td></tr>
<tr><td align="right">415 </td><td align="left">Unsupported Media Type </td></tr>
<tr><td align="right">416 </td><td align="left">Requested range not satisfiable </td></tr>
<tr><td align="right">417 </td><td align="left">Expectation Failed </td></tr>
<tr><td align="right">500 </td><td align="left">Internal Server Error </td></tr>
<tr><td align="right">501 </td><td align="left">Not Implemented </td></tr>
<tr><td align="right">502 </td><td align="left">Bad Gateway </td></tr>
<tr><td align="right">503 </td><td align="left">Service Unavailable </td></tr>
<tr><td align="right">504 </td><td align="left">Gateway Time-out </td></tr>
<tr><td align="right">505 </td><td align="left">HTTP Version not supported </td></tr></table>

</td></tr></table><br></span>
The error codes are given for informational purposes only. The HTTP protocol requires the proper actions after an error is issued. gSOAP's HTTP 1.0/1.1 handling is automatic.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc10.3">
10.3</a>&nbsp;&nbsp;<font color="#0000FF">C/C++ Identifier Name to XML Tag Name Mapping</font></h3><a name="sec:idtrans">
</a>

<div class="p"><!----></div>
One of the "secrets" behind the power and flexibility of gSOAP's encoding and
decoding of service operation names, class names, type identifiers, and struct or
class fields is the ability to specify namespace prefixes with these names that
are used to denote their encoding style. More specifically, a C/C++ identifier
name of the form
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<font size="+1"><span class="roman">[</span></font>namespace_prefix__<font size="+1"><span class="roman">]</span></font>element_name
</td></tr></table><br></i>
where the prefix and the element name are separated by  double underscores will be encoded in XML as
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>element-name ...&#62;
</td></tr></table><br></tt>
The <b>underscore pair</b> (<i>__</i>) separates the namespace prefix from the
element name.  Each namespace prefix has a namespace URI specified by a
namespace mapping table&nbsp;<a href="#sec:nstable">10.4</a>, see also
Section&nbsp;<a href="#sec:namespace">7.1.2</a>.  The namespace URI is a unique identification that
can be associated with the service operations and data types.  The namespace URI
disambiguates potentially identical service operation names and data type names
used by disparate organizations.

<div class="p"><!----></div>
XML element names are NCNames (restricted strings) that MAY contain <b>
hyphens</b>, <b>dots</b>, and <b>underscores</b>.  The special characters in the XML
element names of service operations, structs, classes, typedefs, and fields can be
controlled using the following conventions: A <b>single underscore</b> in a
namespace prefix or identifier name is replaced by a hyphen (<tt>-</tt>) in the
XML element name.  For example, the identifier name <i>SOAP_ENC__ur_type</i>
is represented in XML as <tt>SOAP-ENC:ur-type</tt>.  The sequence <i>_DOT</i> is
replaced by a dot (<tt>.</tt>), and the sequence <i>_USCORE</i> is replaced by
an underscore (<tt>_</tt>) in the corresponding XML element name.  For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;n_s__biz_DOTcom <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*n_s__biz_USCOREname; <br />
};
</td></tr></table><br></i>
is encoded in XML as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;n-s:biz.com xsi:type="n-s:biz.com"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;n-s:biz_name xsi:type="string"&#62;Bizybiz&lt;/n-s:biz_name&#62; <br />
&lt;/n-s:biz.com&#62;
</td></tr></table><br></tt>
Trailing underscores of an identifier name are not translated into the XML
representation. This is useful when an identifier name clashes with a C++
keyword. For example, <tt>return</tt> is often used as an accessor name in a SOAP
response element.  The <tt>return</tt> element can be specified as <i>return_</i>
in the C++ source code. Note that XML should be treated as case sensitive, so
the use of e.g. <i>Return</i> may not always work to avoid a name clash with the
<i><b>return</b></i> keyword.  The use of trailing underscores also allows for
defining <i><b>struct</b></i>s and <i><b>class</b></i>es with essentially the same XML Schema
type name, but that have to be distinguished as seperate C/C++ types.

<div class="p"><!----></div>
For decoding, the underscores in identifier names act as wildcards. An XML
element is parsed and matches the name of an identifier if the name is
identical to the element name (case insensitive) and the underscores in the
identifier name are allowed to match any character in the element name. For
example, the identifier name <i>I_want__soap_fun_the_bea___DOTcom</i>
matches the element name <tt>I-want:SOAP4fun@the-beach.com</tt>.

<div class="p"><!----></div>
By default, <i>soapcpp2</i> generates data bindings in which  all XML elements are and attributes are unqualified:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap x schema namespace: urn:x <br />
<b>struct</b>&nbsp;x__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* name; <br />
};
</td></tr></table><br></i>
where the <i>name</i> element and the <i>type</i> attribute are unqualified in the XML content (for example to facilitate SOAP RPC encoding).

<div class="p"><!----></div>
The rules for SOAP services that are document style are different:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap x schema namespace: urn:x <br />
//gsoap x service style: document <br />
<b>struct</b>&nbsp;x__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* name; <br />
};
</td></tr></table><br></i>
where <i>x</i> is associated with a service. For document style all elements are qualified and attributes are unqualified.

<div class="p"><!----></div>
To force qualification of elements and attributes, use the "form" directive:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap x schema namespace: urn:x <br />
//gsoap x schema form: qualified <br />
<b>struct</b>&nbsp;x__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* name; <br />
};
</td></tr></table><br></i>
You can also use "elementForm" and "attributeForm" directives to (un)qualify element and attributes of the schema, respectively.

<div class="p"><!----></div>
Because the <i>soapcpp2</i>-generated serializers follow the
qualified/unqualified forms of the schemas, there is normally no need to
explicitly qualify struct/class members because automatic encoding rules will
be used.

<div class="p"><!----></div>
If explicit qualification is needed, this can be done using the prefix convention:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap x schema namespace: urn:x <br />
//gsoap y schema namespace: urn:y <br />
<b>struct</b>&nbsp;x__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* xsi__type;  <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* y__name; <br />
};
</td></tr></table><br></i>
which ensures that there cannot be any name clashes between members of the same name defined in different schemas (consider for example <i>name</i> and <i>y__name</i>), but this can clutter the representation when clashes do not occur.

<div class="p"><!----></div>
An alternative to the prefix convention is the use of "<b>colon notation</b>" in the
gSOAP header file. This deviation from the C/C++ syntax allows you to bind
type names and struct and class members to qualified and unqualified XML tag names explicitly,
thus bypassing the default mechanism that automatically qualifies or
unqualifies element and attribute tag names based on the schema
element/attribute form.

<div class="p"><!----></div>
The colon notation for type names, struct/class names and members overrides the prefix qualification rules explicitly:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap x schema namespace: urn:x <br />
//gsoap y schema namespace: urn:y <br />
<b>struct</b>&nbsp;x:record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* xsi:type;  <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* y:name; <br />
};
</td></tr></table><br></i>
where <i>x</i> and <i>y</i> are namespace prefixes that MUST be declared with a directive. The <i>xsi:type</i> member is an XML attribute in the <i>xsi</i> namespace.
The <i>soapcpp2</i> tool maps this to the following struct without the annotations:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// This code is generated from the above by soapcpp2 in soapStub.h: <br />
<b>struct</b>&nbsp;record <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*type;     /* optional attribute of type xsd:string */ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name;     /* optional element of type xsd:string */ <br />
};
</td></tr></table><br></i>
The <i>soapcpp2</i> tool also generates XML schemas with element and attribute
references. That is, <i>y:name</i> is referenced from the <i>y</i> schema by the
<tt>x:record</tt> complexType defined in the <i>x</i> schema.

<div class="p"><!----></div>
The colon notation also allows you to override the element/attribute form to unqualified for qualified schemas:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap x schema namespace: urn:x <br />
//gsoap x schema form: qualified <br />
<b>struct</b>&nbsp;x:record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* :type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* :name; <br />
};
</td></tr></table><br></i>
where the colon notation ensures that both <i>type</i> and <i>name</i> are
unqualified in the XML content, which overrides the default qualified forms of
the <i>x</i> schema.

<div class="p"><!----></div>
Note that the use of colon notation to bind namespace prefixes to type names
(typedef, enum, struct, and class names) translates to code without the
prefixes. This means that name clashes can occur between types with identical unquaified names:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;x:color { RED, WHITE, BLUE }; <br />
<b>enum</b>&nbsp;y:color { YELLOW, ORANGE }; // illegal enum name: name clash with x:color
</td></tr></table><br></i>
while prefixing with double underscores never lead to clashes:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;x__color { RED, WHITE, BLUE }; <br />
<b>enum</b>&nbsp;y__color { YELLOW, ORANGE }; // no name clash
</td></tr></table><br></i>

<div class="p"><!----></div>
Also note that colon notation has a very different role than the C++ scope
operator <i>::</i>. The scope operator cannot be used in places where we need
colon notation, such as struct/class member fields.

<div class="p"><!----></div>
The default mechanism that associates XML tag names with the names of struct
and class member fields can be overriden by "<b>retagging</b>" names with the
annotation of <i>`<i>tag</i>`</i> placed next to the member field name. This is particularly useful to support legacy code for which the fixed naming of member fields cannot be easily changed. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap x schema namespace: urn:x <br />
//gsoap x schema form: qualified <br />
<b>struct</b>&nbsp;x:record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* t`type`;  <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* s`full-name`;  <br />
};
</td></tr></table><br></i>
This maps the <i>t</i> member to the <tt>x:type</tt> XML attribute tag and <i>s</i>
member to the <tt>x:full-name</tt> XML element tag. Note that both tags are namespace
qualified as per schema declaration.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc10.4">
10.4</a>&nbsp;&nbsp;<font color="#0000FF">Namespace Mapping Table</font></h3><a name="sec:nstable">
</a>

<div class="p"><!----></div>
A namespace mapping table MUST be defined by clients and service applications.
The mapping table is used by the serializers and deserializers of the stub and
skeleton routines to produce a valid SOAP payload and to validate an incoming
SOAP payload.  A typical mapping table is shown below:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{&nbsp;&nbsp;&nbsp;// {"ns-prefix", "ns-name"} <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, // MUST be first <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC", "http://schemas.xmlsoap.org/soap/encoding/"}, // MUST be second <br />
&nbsp;&nbsp;&nbsp;{"xsi",      "http://www.w3.org/2001/XMLSchema-instance"}, // MUST be third <br />
&nbsp;&nbsp;&nbsp;{"xsd",      "http://www.w3.org/2001/XMLSchema"}, // Required for XML Schema types <br />
&nbsp;&nbsp;&nbsp;{"ns1",      "urn:my-service-URI"}, // The namespace URI of the service operations <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} // end of table <br />
}; <br />
</td></tr></table><br></i>
Each namespace prefix used by a identifier name in the header file
specification (see Section&nbsp;<a href="#sec:idtrans">10.3</a>) MUST have a binding to a
namespace URI in the mapping table. The end of the namespace mapping table MUST
be indicated by the <i>NULL</i> pair.  The namespace URI matching is case
insensitive. A namespace prefix is distinguished by the occurrence of a pair
of underscores (<i>__</i>) in an identifier.

<div class="p"><!----></div>
An optional namespace pattern MAY be provided with each namespace mapping table
entry.  The patterns provide an alternative namespace matching for the
validation of decoded SOAP messages.  In this pattern, dashes (<i>-</i>) are
single-character wildcards and asterisks (<i>*</i>) are multi-character
wildcards.  For example, to decode different versions of XML Schema type with
different authoring dates, four dashes can be used in place of the specific
dates in the namespace mapping table pattern:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{&nbsp;&nbsp;&nbsp;// {"ns-prefix", "ns-name", "ns-name validation pattern"} <br />
... <br />
&nbsp;&nbsp;&nbsp;{"xsi",      "http://www.w3.org/2001/XMLSchema-instance", "http://www.w3.org/<tt>----</tt>/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd",      "http://www.w3.org/2001/XMLSchema", "http://www.w3.org/<tt>----</tt>/XMLSchema"}, <br />
...
</td></tr></table><br></i>
Or alternatively, asterisks can be used as wildcards for multiple characters:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{&nbsp;&nbsp;&nbsp;// {"ns-prefix", "ns-name", "ns-name validation pattern"} <br />
... <br />
&nbsp;&nbsp;&nbsp;{"xsi",      "http://www.w3.org/2001/XMLSchema-instance", "http://www.w3.org/*/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd",      "http://www.w3.org/2001/XMLSchema", "http://www.w3.org/*/XMLSchema"}, <br />
...
</td></tr></table><br></i>
A namespace mapping table is automatically generated together with a WSDL file
for each namespace prefix that is used for a service operation specified in the header file.
This namespace mapping table has entries for all namespace prefixes.  The
namespace URIs need to be filled in. These appear as <i>http://tempuri.org</i>
in the table.  See Section&nbsp;<a href="#sec:directives">19.2</a> on how to specify the namespace
URIs in the header file.

<div class="p"><!----></div>
For decoding elements with namespace prefixes, the namespace URI associated with the namespace prefix (through the <tt>xmlns</tt>
attribute of an XML element) is searched from the
beginning to the end in a namespace mapping table,
and for every row the following tests are performed as part of the validation process:

<ol type="1">
<li> the string in the second column matches the namespace URI (case insensitive)
<div class="p"><!----></div>
</li>

<li> the string in the optional third column matches the namespace URI (case insensitive), where <i>-</i> is a one-character wildcard and <i>*</i> is a
   multi-character wildcard
<div class="p"><!----></div>
</li>
</ol>
When a match is found, the namespace prefix in the first column of the table is considered semantically identical to the namespace prefix used
by the XML element to be decoded, though the prefix names may differ.
A service will respond with the namespace that it received from a client in case it matches a pattern in the third column.

<div class="p"><!----></div>
For example, let's say we have the following structs:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;a__elt { ... }; <br />
<b>struct</b>&nbsp;b__elt { ... }; <br />
<b>struct</b>&nbsp;k__elt { ... }; <br />
</td></tr></table><br></i>
and a namespace mapping table in the program:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{&nbsp;&nbsp;&nbsp;// {"ns-prefix", "ns-name", "ns-name validation pattern"} <br />
... <br />
&nbsp;&nbsp;&nbsp;{"a", "some uri"}, <br />
&nbsp;&nbsp;&nbsp;{"b", "other uri"}, <br />
&nbsp;&nbsp;&nbsp;{"c", "his uri", "* uri"}, <br />
...
</td></tr></table><br></i>
Then, the following XML elements will match the structs:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;n:elt xmlns:n="some URI"&#62; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;matches the struct name <i>a__elt</i> <br />
... <br />
&lt;m:elt xmlns:m="other URI"&#62; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;matches the struct name <i>b__elt</i> <br />
... <br />
&lt;k:elt xmlns:k="my URI"&#62; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;matches the struct name <i>c__elt</i> <br />
... <br />
</td></tr></table><br></tt>
The response of a service to a client request that uses the namespaces listed above,
will include <tt>my URI</tt> for the name space of element <tt>k</tt>.

<div class="p"><!----></div>
It is possible to use a number of different namespace tables and select the one that is appropriate.
For example, an application might contact many different Web services all using different namespace URIs.
If all the URIs are stored in one table, each service operation invocation will dump the whole namespace
table in the SOAP payload.  There is no technical problem with that, but it can be ugly when the table is large.
To use different namespace tables, declare a pointer to a table and set the pointer to a particular table before service operation
invocation.  For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Namespace namespacesTable1[] = { ... }; <br />
<b>struct</b>&nbsp;Namespace namespacesTable2[] = { ... }; <br />
<b>struct</b>&nbsp;Namespace namespacesTable3[] = { ... }; <br />
<b>struct</b>&nbsp;Namespace *namespaces; <br />
... <br />
<b>struct</b>&nbsp;soap soap; <br />
... <br />
soap_init(&amp;soap); <br />
soap_set_namespaces(&amp;soap, namespaceTable1); <br />
soap_call_remote_method(&amp;soap, URL, Action, ...); <br />
...
</td></tr></table><br></i> 

<div class="p"><!----></div>
 <h2><a name="tth_sEc11">
11</a>&nbsp;&nbsp;<font color="#0000FF">gSOAP Serialization and Deserialization Rules</font></h2>

<div class="p"><!----></div>
This section describes the serialization and deserialization of C and C++ data types for SOAP 1.1 and 1.2 compliant encoding and decoding.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.1">
11.1</a>&nbsp;&nbsp;<font color="#0000FF">SOAP RPC Encoding Versus Document/Literal and xsi:type Info</font></h3>

<div class="p"><!----></div>
The wsdl2h tool automatically generates a header file specialized for SOAP RPC
encoding or document/literal style. The serialization and deserialization rules
for C/C++ objects is almost identical for these styles, except for the
following important issues.

<div class="p"><!----></div>
With SOAP RPC encoding style, care must be taken to ensure typed messages are
produced for interoperability and compatibility reasons. To ensure that the
gSOAP engine automatically generates typed (<tt>xsi:type</tt> attributed)
messages, use <i>soapcpp2</i> option -t, see also Section&nbsp;<a href="#sec:options">9.1</a>.
While gSOAP can handle untyped messages, some toolkits fail to find
deserializers when the <tt>xsi:type</tt> information is absent.

<div class="p"><!----></div>
When starting the development of a gSOAP application from a header file, the
<i>soapcpp2</i> compiler will generate WSDL and schema files for SOAP 1.1
document/literal style by default (use the <i>//gsoap</i> directives to control
this, see Section&nbsp;<a href="#sec:directives">19.2</a>). Use <i>soapcpp2</i> options -2, -e, and
-t to generate code for SOAP 1.2, RPC encoding, and typed messages.

<div class="p"><!----></div>
With SOAP RPC encoding, generic <tt>complexTypes</tt> with
<tt>maxOccurs="unbounded"</tt> are not allowed and SOAP encoded arrays must be
used. Also XML attributes and unions (XML schema <tt>choice</tt>) are not allowed
with SOAP RPC encoding.

<div class="p"><!----></div>
Also with SOAP RPC encoding, multi-reference accessors are common to encode
co-referenced objects and object digraphs. Multi-reference encoding is not
supported in document/literal style, which means that cyclic object digraphs
cannot be serialized (the engine will crash). Also DAGs are represented as XML
trees in document/literal style messaging.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.2">
11.2</a>&nbsp;&nbsp;<font color="#0000FF">Primitive Type Encoding</font></h3>

<div class="p"><!----></div>
The default encoding rules for the primitive C and C++ data types are given in the table below:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Type</b></font> </td><td align="left"><font color="#FF0000"><b>XSD Type</b></font> </td></tr>
<tr><td align="left"><i><b>bool</b></i> </td><td align="left"><tt>boolean</tt> </td></tr>
<tr><td align="left"><i><b>char</b>*</i> (C string) </td><td align="left"><tt>string</tt> </td></tr>
<tr><td align="left"><i><b>char</b></i> </td><td align="left"><tt>byte</tt> </td></tr>
<tr><td align="left"><i><b>long</b>&nbsp;<b>double</b></i> </td><td align="left"><tt>decimal</tt> (with #import "custom/long_double.h") </td></tr>
<tr><td align="left"><i><b>double</b></i> </td><td align="left"><tt>double</tt> </td></tr>
<tr><td align="left"><i><b>float</b></i> </td><td align="left"><tt>float</tt> </td></tr>
<tr><td align="left"><i><b>int</b></i> </td><td align="left"><tt>int</tt> </td></tr>
<tr><td align="left"><i><b>long</b></i> </td><td align="left"><tt>long</tt> </td></tr>
<tr><td align="left"><i>LONG64</i> </td><td align="left"><tt>long</tt> </td></tr>
<tr><td align="left"><i><b>long</b>&nbsp;<b>long</b></i> </td><td align="left"><tt>long</tt> </td></tr>
<tr><td align="left"><i><b>short</b></i> </td><td align="left"><tt>short</tt> </td></tr>
<tr><td align="left"><i>time_t</i> </td><td align="left"><tt>dateTime</tt> </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;tm</i> </td><td align="left"><tt>dateTime</tt> (with #import "custom/struct_tm.h") </td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>char</b></i> </td><td align="left"><tt>unsignedByte</tt> </td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>int</b></i> </td><td align="left"><tt>unsignedInt</tt> </td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>long</b></i> </td><td align="left"><tt>unsignedLong</tt> </td></tr>
<tr><td align="left"><i>ULONG64</i> </td><td align="left"><tt>unsignedLong</tt> </td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>long</b>&nbsp;<b>long</b></i> </td><td align="left"><tt>unsignedLong</tt> </td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>short</b></i> </td><td align="left"><tt>unsignedShort</tt> </td></tr>
<tr><td align="left"><i>wchar_t*</i> </td><td align="left"><tt>string</tt> </td></tr></table>

</td></tr></table><br></span>
Objects of type <i><b>void</b></i> and <i><b>void</b>*</i> cannot be encoded.
Enumerations and bit masks are supported as well, see&nbsp;<a href="#sec:enum">11.4</a>.

<div class="p"><!----></div>
		     <h3><a name="tth_sEc11.3">
11.3</a>&nbsp;&nbsp;<font color="#0000FF">How to Represent Primitive C/C++ Types as XSD Types</font></h3><a name="sec:primitive">
</a>

<div class="p"><!----></div>
By default, encoding of the primitive types will take place as per SOAP
encoding style.  The encoding can be changed to any XML Schema type (XSD type) with an
optional namespace prefix by using a <i><b>typedef</b></i> in the header file input to
the gSOAP <i>soapcpp2</i> tool. The declaration enables the
implementation of built-in XML Schema types (also known as XSD types) such as
<tt>positiveInteger</tt>, <tt>xsd:anyURI</tt>, and <tt>xsd:date</tt> for which no
built-in data structures in C and C++ exist but which can be represented using
standard data structures such as strings, integers, and floats.

<div class="p"><!----></div>
The <i><b>typedef</b></i> declaration is frequently used for convenience in C. A
<i><b>typedef</b></i> declares a type name for a (complex) type expression. The type
name can then be used in other declarations in place of the more complex type
expression, which often improves the readability of the program code.

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> compiler interprets <i><b>typedef</b></i> declarations the same way as a
regular C compiler interprets them, i.e.&nbsp;as types in declarations. In addition
however, the gSOAP <i>soapcpp2</i> compiler will also use the type name in the encoding of the
data in SOAP.  The <i><b>typedef</b></i> name will appear as the XML element name of
an independent element and as the value of the <tt>xsi:type</tt> attribute in the
SOAP payload.

<div class="p"><!----></div>
Many built-in primitive and derived XSD types such as <tt>xsd:anyURI</tt>,
<tt>positiveInteger</tt>, and <tt>decimal</tt> can be stored by standard primitive
data structures in C++, such as strings, integers, floats, and doubles.
To serialize strings, integers, floats, and doubles as built-in primitive and
derived XSD types, a <i><b>typedef</b></i> declaration can be used
to declare an XSD type.

<div class="p"><!----></div>
For example, the declaration
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>int</b>&nbsp;xsd__positiveInteger;
</td></tr></table><br></i>
creates a named type <i>positiveInteger</i> which is represented by <i><b>unsigned</b>&nbsp;<b>int</b></i> in C++. For example, the encoding of a
<i>positiveInteger</i> value <i>3</i> is
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;positiveInteger xsi:type="xsd:positiveInteger"&#62;3&lt;/positiveInteger&#62;
</td></tr></table><br></tt>
The built-in XML Schema datatype hierarchy from the XML Schema Part 2 documentation <a href="http://www.w3.org/TR/xmlschema-2"><tt>http://www.w3.org/TR/xmlschema-2</tt></a> is depicted below.

<div class="p"><!----></div>
<a name="tth_fIg1">
</a> 
<center><img src="http://www.w3.org/TR/xmlschema-2/type-hierarchy.gif"/>
</center>

<center>Figure 1: Built-in Datatype Hierarchy</center>

<div class="p"><!----></div>
The built-in primitive and derived numerical XML Schema types are listed below together with their recommended <i><b>typedef</b></i>
declarations. Note that the SOAP encoding schemas for primitive types are derived from the built-in XML Schema types, so
<i>SOAP_ENC__</i> can be used as a namespace prefix instead of <i>xsd__</i>.

<dl compact="compact">
 <dt><b><tt>xsd:anyURI</tt></b></dt>
	<dd>
Represents a Uniform Resource Identifier Reference (URI).
Each URI scheme imposes specialized syntax rules for URIs in that scheme, including restrictions
on the syntax of allowed fragment identifiers.
It is recommended to use strings to store <tt>xsd:anyURI</tt> XML Schema types. The recommended type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__anyURI;
</td></tr></table><br></i></dd>
 <dt><b><tt>xsd:base64Binary</tt></b></dt>
	<dd>
Represents Base64-encoded arbitrary binary data.
For using the <tt>xsd:base64Binary</tt> XSD Schema type, the use of the base64Binary representation of a dynamic array is <b>strongly</b> recommended,
see Section&nbsp;<a href="#sec:base64binary">11.12</a>. However, the
type can also be declared as a string and the encoding will be string-based:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__base64Binary;
</td></tr></table><br></i>
With this approach, it is the responsibility of the application to make sure the string content is according to the Base64 Content-Transfer-Encoding defined in Section 6.8 of RFC 2045.</dd>
 <dt><b><tt>xsd:boolean</tt></b></dt>
	<dd>
For declaring an <tt>xsd:boolean</tt> XSD Schema type, the use of a bool is <b>strongly</b> recommended.
If a pure C compiler is used that does not support the <i>bool</i> type, see Section&nbsp;<a href="#sec:boolean">11.4.5</a>.
The corresponding type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>bool</b>&nbsp;xsd__boolean;
</td></tr></table><br></i>
Type <i>xsd__boolean</i> declares a Boolean (0 or 1), which is encoded as
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:boolean xsi:type="xsd:boolean"&#62;...&lt;/xsd:boolean&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:byte</tt></b></dt>
	<dd>
Represents a byte (-128...127). The corresponding type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;xsd__byte;
</td></tr></table><br></i>
Type <i>xsd__byte</i> declares a byte which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:byte xsi:type="xsd:byte"&#62;...&lt;/xsd:byte&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:dateTime</tt></b></dt>
	<dd>
Represents a date and time. The lexical representation is according to the ISO 8601 extended format CCYY-MM-DDThh:mm:ss where "CC"
represents the century, "YY" the year, "MM" the month and "DD" the day, preceded by an optional leading "-" sign to indicate a
negative number. If the sign is omitted, "+" is assumed. The letter "T" is the date/time separator and "hh", "mm", "ss" represent
hour, minute and second respectively.
It is recommended to use the <i>time_t</i> type to store <tt>xsd:dateTime</tt> XSD Schema types and the type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;time_t xsd__dateTime;
</td></tr></table><br></i>
However, note that calendar times  before  the year 1902  or after
the year 2037 cannot be represented. Upon receiving a date outside this range,
the <i>time_t</i> value will be set to -1.

<div class="p"><!----></div>
Strings (<i><b>char</b>*</i>) can be used to store <tt>xsd:dateTime</tt> XSD Schema types. The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__dateTime;
</td></tr></table><br></i>
In this case, it is up to the application to read and set the dateTime representation.</dd>
 <dt><b><tt>xsd:date</tt></b></dt>
	<dd>
Represents a date.
The lexical representation for date is the reduced (right truncated) lexical representation for dateTime: CCYY-MM-DD.
It is recommended to use strings (<i><b>char</b>*</i>) to store <tt>xsd:date</tt> XSD Schema types. The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__date;
</td></tr></table><br></i></dd>
 <dt><b><tt>xsd:decimal</tt></b></dt>
	<dd>
Represents arbitrary precision decimal numbers.
It is recommended to use the <b>double</b> type to store <tt>xsd:decimal</tt> XSD Schema types and the type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>double</b>&nbsp;xsd__decimal;
</td></tr></table><br></i>
Type <i>xsd__decimal</i> declares a double floating point number which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:double xsi:type="xsd:decimal"&#62;...&lt;/xsd:double&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:double</tt></b></dt>
	<dd>
Corresponds to the IEEE double-precision 64-bit floating point type. The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>double</b>&nbsp;xsd__double;
</td></tr></table><br></i>
Type <i>xsd__double</i> declares a double floating point number which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:double xsi:type="xsd:double"&#62;...&lt;/xsd:double&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:duration</tt></b></dt>
	<dd>
Represents a duration of time.
The lexical representation for duration is the ISO 8601 extended format PnYn MnDTnH nMnS, where nY represents
the number of years, nM the number of months, nD the number of days, T is the date/time separator, nH the number of
hours, nM the number of minutes and nS the number of seconds. The number of seconds can include decimal digits to
arbitrary precision.
It is recommended to use strings (<i><b>char</b>*</i>) to store <tt>xsd:duration</tt> XSD Schema types. The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__duration;
</td></tr></table><br></i></dd>
 <dt><b><tt>xsd:float</tt></b></dt>
	<dd>
Corresponds to the IEEE single-precision 32-bit floating point type. The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>float</b>&nbsp;xsd__float;
</td></tr></table><br></i>
Type <i>xsd__float</i> declares a floating point number which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:float xsi:type="xsd:float"&#62;...&lt;/xsd:float&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:hexBinary</tt></b></dt>
	<dd>
Represents arbitrary hex-encoded binary data.  It has a lexical representation where each binary octet is encoded as a character
tuple, consisting of two hexadecimal digits ([0-9a-fA-F]) representing the octet code. For example, "0FB7" is a hex encoding for
the 16-bit integer 4023 (whose binary representation is 111110110111.
For using the <tt>xsd:hexBinary</tt> XSD Schema type, the use of the hexBinary representation of a dynamic array is <b>strongly</b> recommended,
see Section&nbsp;<a href="#sec:hexbinary">11.13</a>. However, the
type can also be declared as a string and the encoding will be string-based:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__hexBinary;
</td></tr></table><br></i>
With this approach, it is solely the responsibility of the application to make sure the string content consists of a sequence of octets.</dd>
 <dt><b><tt>xsd:int</tt></b></dt>
	<dd>
Corresponds to a 32-bit integer in the range -2147483648 to 2147483647.
If the C++ compiler supports 32-bit <i><b>int</b></i> types, the type declaration can use the <i><b>int</b></i> type:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>int</b>&nbsp;xsd__int;
</td></tr></table><br></i>
Otherwise, the C++ compiler supports 16-bit <i><b>int</b></i> types and the type declaration should use the <i><b>long</b></i> type:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>long</b>&nbsp;xsd__int;
</td></tr></table><br></i>
Type <i>xsd__int</i> declares a 32-bit integer which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:int xsi:type="xsd:int"&#62;...&lt;/xsd:int&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:integer</tt></b></dt>
	<dd>
Corresponds to an unbounded integer.
Since C++ does not support unbounded integers as a standard feature, the recommended type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>long</b>&nbsp;<b>long</b>&nbsp;xsd__integer;
</td></tr></table><br></i>
Type <i>xsd__integer</i> declares a 64-bit integer which is encoded as an unbounded <tt>xsd:integer</tt>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:integer xsi:type="xsd:integer"&#62;...&lt;/xsd:integer&#62;
</td></tr></table><br></tt>
Another possibility is to use strings to represent unbounded integers and do the translation in code.</dd>
 <dt><b><tt>xsd:long</tt></b></dt>
	<dd>
Corresponds to a 64-bit integer in the range -9223372036854775808 to 9223372036854775807.
The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>long</b>&nbsp;<b>long</b>&nbsp;xsd__long;
</td></tr></table><br></i>
Or in Visual C++:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;LONG64 xsd__long;
</td></tr></table><br></i>
Type <i>xsd__long</i> declares a 64-bit integer which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:long xsi:type="xsd:long"&#62;...&lt;/xsd:long&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:negativeInteger</tt></b></dt>
	<dd>
Corresponds to a negative unbounded integer ( &lt; 0).
Since C++ does not support unbounded integers as a standard feature, the recommended type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>long</b>&nbsp;<b>long</b>&nbsp;xsd__negativeInteger;
</td></tr></table><br></i>
Type <i>xsd__negativeInteger</i> declares a 64-bit integer which is encoded as a <tt>xsd:negativeInteger</tt>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:negativeInteger xsi:type="xsd:negativeInteger"&#62;...&lt;/xsd:negativeInteger&#62;
</td></tr></table><br></tt>
Another possibility is to use strings to represent unbounded integers and do the translation in code.</dd>
 <dt><b><tt>xsd:nonNegativeInteger</tt></b></dt>
	<dd>
Corresponds to a non-negative unbounded integer ( &gt; 0).
Since C++ does not support unbounded integers as a standard feature, the recommended type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>long</b>&nbsp;<b>long</b>&nbsp;xsd__nonNegativeInteger;
</td></tr></table><br></i>
Type <i>xsd__nonNegativeInteger</i> declares a 64-bit unsigned integer which is encoded as a non-negative unbounded <tt>xsd:nonNegativeInteger</tt>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:nonNegativeInteger xsi:type="xsd:nonNegativeInteger"&#62;...&lt;/xsd:nonNegativeInteger&#62;
</td></tr></table><br></tt>
Another possibility is to use strings to represent unbounded integers and do the translation in code.</dd>
 <dt><b><tt>xsd:nonPositiveInteger</tt></b></dt>
	<dd>
Corresponds to a non-positive unbounded integer ( &#8804; 0).
Since C++ does not support unbounded integers as a standard feature, the recommended type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>long</b>&nbsp;<b>long</b>&nbsp;xsd__nonPositiveInteger;
</td></tr></table><br></i>
Type <i>xsd__nonPositiveInteger</i> declares a 64-bit integer which is encoded as a <tt>xsd:nonPositiveInteger</tt>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:nonPositiveInteger xsi:type="xsd:nonPositiveInteger"&#62;...&lt;/xsd:nonPositiveInteger&#62;
</td></tr></table><br></tt>
Another possibility is to use strings to represent unbounded integers and do the translation in code.</dd>
 <dt><b><tt>xsd:normalizedString</tt></b></dt>
	<dd>
Represents normalized character strings.
Normalized character strings do not contain the carriage return (#xD), line feed (#xA) nor tab (#x9) characters.
It is recommended to use strings to store <tt>xsd:normalizeString</tt> XSD Schema types.
The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__normalizedString;
</td></tr></table><br></i>
Type <i>xsd__normalizedString</i> declares a string type which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:normalizedString xsi:type="xsd:normalizedString"&#62;...&lt;/xsd:normalizedString&#62;
</td></tr></table><br></tt>
It is solely the responsibility of the application to make sure the strings do not contain carriage return (#xD), line feed (#xA)
and tab (#x9) characters.</dd>
 <dt><b><tt>xsd:positiveInteger</tt></b></dt>
	<dd>
Corresponds to a positive unbounded integer ( &#8805; 0).
Since C++ does not support unbounded integers as a standard feature, the recommended type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>long</b>&nbsp;<b>long</b>&nbsp;xsd__positiveInteger;
</td></tr></table><br></i>
Type <i>xsd__positiveInteger</i> declares a 64-bit unsigned integer which is encoded as a <tt>xsd:positiveInteger</tt>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:positiveInteger xsi:type="xsd:positiveInteger"&#62;...&lt;/xsd:positiveInteger&#62;
</td></tr></table><br></tt>
Another possibility is to use strings to represent unbounded integers and do the translation in code.</dd>
 <dt><b><tt>xsd:short</tt></b></dt>
	<dd>
Corresponds to a 16-bit integer in the range -32768 to 32767.
The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>short</b>&nbsp;xsd__short;
</td></tr></table><br></i>
Type <i>xsd__short</i> declares a short 16-bit integer which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:short xsi:type="xsd:short"&#62;...&lt;/xsd:short&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:string</tt></b></dt>
	<dd>
Represents character strings. The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string;
</td></tr></table><br></i>
Type <i>xsd__string</i> declares a string type which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:string xsi:type="xsd:string"&#62;...&lt;/xsd:string&#62;
</td></tr></table><br></tt>
The type declaration for wide character strings is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;wchar_t *xsd__string;
</td></tr></table><br></i>
Both type of strings can be used at the same time, but requires one typedef name to be changed by appending an underscore which is
invisible in XML. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;wchar_t *xsd__string_;
</td></tr></table><br></i></dd>
 <dt><b><tt>xsd:time</tt></b></dt>
	<dd>
Represents a time.  The lexical representation for time is the left truncated lexical representation for dateTime: hh:mm:ss.sss
with optional following time zone indicator.
It is recommended to use strings (<i><b>char</b>*</i>) to store <tt>xsd:time</tt> XSD Schema types. The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__time;
</td></tr></table><br></i></dd>
 <dt><b><tt>xsd:token</tt></b></dt>
	<dd>
Represents tokenized strings.
Tokens are strings that do not contain the
line feed (#xA) nor tab (#x9) characters, that have no leading or trailing spaces (#x20) and that have no internal
sequences of two or more spaces.
It is recommended to use strings to store <tt>xsd:token</tt> XSD Schema types.
The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__token;
</td></tr></table><br></i>
Type <i>xsd__token</i> declares a string type which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:token xsi:type="xsd:token"&#62;...&lt;/xsd:token&#62;
</td></tr></table><br></tt>
It is solely the responsibility of the application to make sure the strings do not contain the line feed (#xA) nor tab (#x9)
characters, that have no leading or trailing spaces (#x20) and that have no internal sequences of two or more spaces.</dd>
 <dt><b><tt>xsd:unsignedByte</tt></b></dt>
	<dd>
Corresponds to an 8-bit unsigned integer in the range 0 to 255.
The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;xsd__unsignedByte;
</td></tr></table><br></i>
Type <i>xsd__unsignedByte</i> declares a unsigned 8-bit integer which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:unsignedByte xsi:type="xsd:unsignedByte"&#62;...&lt;/xsd:unsignedByte&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:unsignedInt</tt></b></dt>
	<dd>
Corresponds to a 32-bit unsigned integer in the range 0 to 4294967295.
If the C++ compiler supports 32-bit <i><b>int</b></i> types, the type declaration can use the <i><b>int</b></i> type:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>int</b>&nbsp;xsd__unsignedInt;
</td></tr></table><br></i>
Otherwise, the C++ compiler supports 16-bit <i><b>int</b></i> types and the type declaration should use the <i><b>long</b></i> type:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>long</b>&nbsp;xsd__unsignedInt;
</td></tr></table><br></i>
Type <i>xsd__unsignedInt</i> declares an unsigned 32-bit integer which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:unsignedInt xsi:type="xsd:unsignedInt"&#62;...&lt;/xsd:unsignedInt&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:unsignedLong</tt></b></dt>
	<dd>
Corresponds to a 64-bit unsigned integer in the range 0 to 18446744073709551615.
The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>long</b>&nbsp;<b>long</b>&nbsp;xsd__unsignedLong;
</td></tr></table><br></i>
Or in Visual C++:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;ULONG64 xsd__unsignedLong;
</td></tr></table><br></i>
Type <i>xsd__unsignedLong</i> declares an unsigned 64-bit integer which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:unsignedLong xsi:type="xsd:unsignedLong"&#62;...&lt;/xsd:unsignedLong&#62;
</td></tr></table><br></tt></dd>
 <dt><b><tt>xsd:unsignedShort</tt></b></dt>
	<dd>
Corresponds to a 16-bit unsigned integer in the range 0 to 65535.
The type declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>short</b>&nbsp;xsd__unsignedShort;
</td></tr></table><br></i>
Type <i>xsd__unsginedShort</i> declares an unsigned short 16-bit integer which is encoded as 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:unsignedShort xsi:type="xsd:unsignedShort"&#62;...&lt;/xsd:unsignedShort&#62;
</td></tr></table><br></tt></dd>
</dl>
Other XSD Schema types such as <tt>gYearMonth</tt>, <tt>gYear</tt>, <tt>gMonthDay</tt>, <tt>gDay</tt>, <tt>xsd:gMonth</tt>, <tt>QName</tt>,
<tt>NOTATION</tt>, etc., can be encoded similarly using a <i><b>typedef</b></i> declaration.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.3.1">
11.3.1</a>&nbsp;&nbsp;<font color="#0000FF">How to Use Multiple C/C++ Types for a Single Primitive XSD Type</font></h4>

<div class="p"><!----></div>
Trailing underscores (see Section&nbsp;<a href="#sec:idtrans">10.3</a>) can be used in the type
name in a <i><b>typedef</b></i> to enable the declaration of multiple storage formats
for a single XML Schema type. For example, one part of a C/C++ application's
data structure may use plain strings while another part may use wide character
strings.  To enable this simultaneous use, declare:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string; <br />
<b>typedef</b>&nbsp;wchar_t *xsd__string_;
</td></tr></table><br></i>
Now, the <i>xsd__string</i> and <i>xsd__string_</i> types will both be encoded
and decoded as XML string types and the use of trailing underscores allows
multiple declarations for a single XML Schema type.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.3.2">
11.3.2</a>&nbsp;&nbsp;<font color="#0000FF">How to use C++ Wrapper Classes to Specify Polymorphic Primitive Types</font></h4><a name="sec:primclass">
</a>

<div class="p"><!----></div>
SOAP 1.1 supports polymorphic types, because XSD Schema types form a hierarchy.
The root of the hierarchy is called <tt>xsd:anyType</tt> (<tt>xsd:ur-type</tt> in the
older 1999 schema).  So, for example, an array of <tt>xsd:anyType</tt> in SOAP may
actually contain any mix of element types that are the derived types of the
root type.  The use of polymorphic types is indicated by the WSDL and schema
descriptions of a Web service and can therefore be predicted/expected for each
particular case.

<div class="p"><!----></div>
On the one hand, the <i><b>typedef</b></i> construct provides a convenient way to
associate C/C++ types with XML Schema types and makes it easy to incorporate
these types in a (legacy) C/C++ application.  However, on the other hand the
<i><b>typedef</b></i> declarations cannot be used to support polymorphic XML Schema
types.  Most SOAP clients and services do not use polymorphic types.  In case
they do, the primitive polymorphic types can be declared as a hierarchy of C++
<i><b>class</b></i>es that can be used simultaneously with the <i><b>typedef</b></i>
declarations.

<div class="p"><!----></div>
The general form of a primitive type declaration that is derived from a super type is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;xsd__type_name: <font size="+1"><span class="roman">[</span></font><b>public</b>&nbsp;xsd__super_type_name<font size="+1"><span class="roman">]</span></font> <br />
{ <b>public</b>: <u><span class="roman">Type</span></u> __item; <br />
&nbsp;&nbsp;&nbsp;<font size="+1"><span class="roman">[</span></font><b>public</b>:<font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font><b>private</b><font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font><b>protected</b>:<font size="+1"><span class="roman">]</span></font> <br />
&nbsp;&nbsp;&nbsp;method1; <br />
&nbsp;&nbsp;&nbsp;method2; <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
where <u><span class="roman">Type</span></u> is a primitive C type. The <i>__item</i> field MUST be the first
field in this wrapper class.

<div class="p"><!----></div>
For example, the XML Schema type hierarchy can be copied to C++ with the following declarations:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;xsd__anyType { }; <br />
<b>class</b>&nbsp;xsd__anySimpleType: <b>public</b>&nbsp;xsd__anyType { }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__anyURI; <br />
<b>class</b>&nbsp;xsd__anyURI_: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: xsd__anyURI __item; }; <br />
<b>typedef</b>&nbsp;<b>bool</b>&nbsp;xsd__boolean; <br />
<b>class</b>&nbsp;xsd__boolean_: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: xsd__boolean __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__date; <br />
<b>class</b>&nbsp;xsd__date_: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: xsd__date __item; }; <br />
<b>typedef</b>&nbsp;time_t xsd__dateTime; <br />
<b>class</b>&nbsp;xsd__dateTime_: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: xsd__dateTime __item; }; <br />
<b>typedef</b>&nbsp;<b>double</b>&nbsp;xsd__double; <br />
<b>class</b>&nbsp;xsd__double_: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: xsd__double __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__duration; <br />
<b>class</b>&nbsp;xsd__duration_: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: xsd__duration __item; }; <br />
<b>typedef</b>&nbsp;<b>float</b>&nbsp;xsd__float; <br />
<b>class</b>&nbsp;xsd__float_: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: xsd__float __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__time; <br />
<b>class</b>&nbsp;xsd__time_: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: xsd__time __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__decimal; <br />
<b>class</b>&nbsp;xsd__decimal_: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: xsd__decimal __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__integer; <br />
<b>class</b>&nbsp;xsd__integer_: <b>public</b>&nbsp;xsd__decimal_ { <b>public</b>: xsd__integer __item; }; <br />
<b>typedef</b>&nbsp;LONG64 xsd__long; <br />
<b>class</b>&nbsp;xsd__long_: <b>public</b>&nbsp;xsd__integer_ { <b>public</b>: xsd__long __item; }; <br />
<b>typedef</b>&nbsp;<b>long</b>&nbsp;xsd__int; <br />
<b>class</b>&nbsp;xsd__int_: <b>public</b>&nbsp;xsd__long_ { <b>public</b>: xsd__int __item; }; <br />
<b>typedef</b>&nbsp;<b>short</b>&nbsp;xsd__short; <br />
<b>class</b>&nbsp;xsd__short_: <b>public</b>&nbsp;xsd__int_ { <b>public</b>: xsd__short __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;xsd__byte; <br />
<b>class</b>&nbsp;xsd__byte_: <b>public</b>&nbsp;xsd__short_ { <b>public</b>: xsd__byte __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__nonPositiveInteger; <br />
<b>class</b>&nbsp;xsd__nonPositiveInteger_: <b>public</b>&nbsp;xsd__integer_ { <b>public</b>: xsd__nonPositiveInteger __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__negativeInteger; <br />
<b>class</b>&nbsp;xsd__negativeInteger_: <b>public</b>&nbsp;xsd__nonPositiveInteger_ { <b>public</b>: xsd__negativeInteger __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__nonNegativeInteger; <br />
<b>class</b>&nbsp;xsd__nonNegativeInteger_: <b>public</b>&nbsp;xsd__integer_ { <b>public</b>: xsd__nonNegativeInteger __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__positiveInteger; <br />
<b>class</b>&nbsp;xsd__positiveInteger_: <b>public</b>&nbsp;xsd__nonNegativeInteger_ { <b>public</b>: xsd__positiveInteger __item; }; <br />
<b>typedef</b>&nbsp;ULONG64 xsd__unsignedLong; <br />
<b>class</b>&nbsp;xsd__unsignedLong_: <b>public</b>&nbsp;xsd__nonNegativeInteger_ { <b>public</b>: xsd__unsignedLong __item; }; <br />
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>long</b>&nbsp;xsd__unsignedInt; <br />
<b>class</b>&nbsp;xsd__unsignedInt_: <b>public</b>&nbsp;xsd__unsginedLong_ { <b>public</b>: xsd__unsignedInt __item; }; <br />
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>short</b>&nbsp;xsd__unsignedShort; <br />
<b>class</b>&nbsp;xsd__unsignedShort_: <b>public</b>&nbsp;xsd__unsignedInt_ { <b>public</b>: xsd__unsignedShort __item; }; <br />
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;xsd__unsignedByte; <br />
<b>class</b>&nbsp;xsd__unsignedByte_: <b>public</b>&nbsp;xsd__unsignedShort_ { <b>public</b>: xsd__unsignedByte __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string; <br />
<b>class</b>&nbsp;xsd__string_: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: xsd__string __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__normalizedString; <br />
<b>class</b>&nbsp;xsd__normalizedString_: <b>public</b>&nbsp;xsd__string_ { <b>public</b>: xsd__normalizedString __item; }; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__token; <br />
<b>class</b>&nbsp;xsd__token_: <b>public</b>&nbsp;xsd__normalizedString_ { <b>public</b>: xsd__token __item; }; <br />
</td></tr></table><br></i>
Note the use of the trailing underscores for the <i><b>class</b></i> names to distinguish the <i><b>typedef</b></i> type names from the
<i><b>class</b></i> names.  Only the most frequently used built-in schema types are shown.
It is also allowed to include the <i>xsd:base64Binary</i> and <i>xsd:hexBinary</i> types in the hierarchy:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;xsd__base64Binary: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: <b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <b>int</b>&nbsp;__size; }; <br />
<b>class</b>&nbsp;xsd__hexBinary: <b>public</b>&nbsp;xsd__anySimpleType { <b>public</b>: <b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <b>int</b>&nbsp;__size; };
</td></tr></table><br></i>
See Sections&nbsp;<a href="#sec:base64binary">11.12</a> and&nbsp;<a href="#sec:hexbinary">11.13</a>.

<div class="p"><!----></div>
Methods are allowed to be added to the classes above, such as constructors and getter/setter methods, see Section&nbsp;<a href="#sec:gettersetter">11.6.4</a>.

<div class="p"><!----></div>
Wrapper structs are supported as well, similar to wrapper classes.  But they cannot be used
to implement polymorphism.  Rather, the wrapper structs facilitate the use of XML attributes
with a primitive typed object, see&nbsp;<a href="#sec:attributes">11.6.7</a>.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.3.3">
11.3.3</a>&nbsp;&nbsp;<font color="#0000FF">XSD Schema Type Decoding Rules</font></h4>

<div class="p"><!----></div>
The decoding rules for the primitive C and C++ data types is given in the table below:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Type</b></font> </td><td align="left"><font color="#FF0000"><b>Allows Decoding of</b></font> </td><td align="left"><font color="#FF0000"><b>Precision Lost?</b></font> </td></tr>
<tr><td align="left"><i><b>bool</b></i> </td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>boolean</tt> </td><td align="left">no </td></tr>
<tr><td align="left"><i><b>char</b>*</i> (C string) </td><td align="left">any type, see&nbsp;<a href="#sec:smart">11.3.5</a> </td><td align="left">no </td></tr>
<tr><td align="left"><i>wchar_t *</i> (wide string) </td><td align="left">any type, see&nbsp;<a href="#sec:smart">11.3.5</a> </td><td align="left">no </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>double</b></i>	</td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>double</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>float</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>long</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>int</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>short</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>byte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedLong</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedInt</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedShort</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>decimal</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>integer</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>positiveInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>negativeInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>nonPositiveInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>nonNegativeInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>float</b></i>	</td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>float</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>long</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>int</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>short</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>byte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedLong</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedInt</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedShort</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>decimal</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>integer</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>positiveInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>negativeInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>nonPositiveInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>nonNegativeInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>long</b>&nbsp;<b>long</b></i> </td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>long</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>int</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>short</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>byte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedLong</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedInt</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedShort</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>integer</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>positiveInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>negativeInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>nonPositiveInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>nonNegativeInteger</tt> </td><td align="left">possibly </td></tr></table>

</td></tr></table><br></span>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Type</b></font> </td><td align="left"><font color="#FF0000"><b>Allows Decoding of</b></font> </td><td align="left"><font color="#FF0000"><b>Precision Lost?</b></font> </td></tr>
<tr><td align="left"><i><b>long</b></i>	</td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>long</tt> </td><td align="left">possibly, if <i><b>long</b></i> is 32 bit </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>int</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>short</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>byte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedLong</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedInt</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedShort</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>int</b></i>	</td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>int</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>short</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>byte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedInt</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedShort</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>short</b></i>	</td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>short</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>byte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedShort</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>char</b></i>	</td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>byte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>long</b>&nbsp;<b>long</b></i> </td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedLong</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedInt</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedShort</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>positiveInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>nonNegativeInteger</tt> </td><td align="left">possibly </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>long</b></i> </td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedLong</tt> </td><td align="left">possibly, if <i><b>long</b></i> is 32 bit </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedInt</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedShort</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>int</b></i> </td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedInt</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedShort</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>short</b></i> </td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedShort</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i><b>unsigned</b>&nbsp;<b>char</b></i> </td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>unsignedByte</tt> </td><td align="left">no </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left"><i>time_t</i>	</td><td align="left"><tt><font size="+1"><span class="roman">[</span></font>xsd:<font size="+1"><span class="roman">]</span></font>dateTime</tt> </td><td align="left">no(?) </td></tr>
<tr><td align="left"></td></tr></table>

</td></tr></table><br></span>
Due to limitations in representation of certain primitive C++ types, a possible loss of accuracy may occur with the decoding of certain XSD Schema types as is indicated in the table. The table does not indicate the possible loss of precision of floating point values due to the textual representation of floating point values in SOAP.

<div class="p"><!----></div>
All explicitly declared XSD Schema encoded primitive types adhere to the same decoding rules. For example, the following declaration:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>unsigned</b>&nbsp;<b>long</b>&nbsp;<b>long</b>&nbsp;xsd__nonNegativeInteger;
</td></tr></table><br></i>
enables the encoding and decoding of <tt>xsd:nonNegativeInteger</tt> XSD Schema types (although decoding takes place with a possible
loss of precision).
The declaration also allows decoding of <tt>xsd:positiveInteger</tt> XSD Schema types, because of the storage as a <i><b>unsigned</b>&nbsp;<b>long</b>&nbsp;<b>long</b></i> data type.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.3.4">
11.3.4</a>&nbsp;&nbsp;<font color="#0000FF">Multi-Reference Strings</font></h4>

<div class="p"><!----></div>
If more than one <i><b>char</b></i> pointer points to the same string, the string is encoded as a multi-reference value.
Consider for example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>char</b>&nbsp;*s = "hello", *t = s;
</td></tr></table><br></i>
The <i>s</i> and <i>t</i> variables are assigned the same string, and when serialized, <i>t</i> refers to the content of <i>s</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;string id="123" xsi:type="string"&#62;hello&lt;/string&#62; <br />
... <br />
&lt;string href="#123"/&#62;
</td></tr></table><br></tt>
The example assumed that <i>s</i> and <i>t</i> are encoded as independent elements.

<div class="p"><!----></div>
Note: the use of <i><b>typedef</b></i> to declare a string type such as <i>xsd__string</i> will not affect the multi-reference string
encoding.  However, strings declared with different <i><b>typedef</b></i>s will never be considered multi-reference even when they point
to the same string.  For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__anyURI; <br />
xsd__anyURI *s = "http://www.myservice.com"; <br />
xsd__string *t = s;
</td></tr></table><br></i>
The variables <i>s</i> and <i>t</i> point to the same string, but since they are considered different types their content will not
be shared in the SOAP payload through a multi-referenced string.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.3.5">
11.3.5</a>&nbsp;&nbsp;<font color="#0000FF">"Smart String" Mixed-Content Decoding</font></h4><a name="sec:smart">
</a>

<div class="p"><!----></div>
The implementation of string decoding in gSOAP allows for mixed content decoding. If the SOAP payload contains a complex data type in place of
a string, the complex data type is decoded in the string as plain XML text.

<div class="p"><!----></div>
For example, suppose the <i>getInfo</i> service operation returns some detailed information. The service operation is declared as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of header file "getInfo.h": <br />
getInfo(<b>char</b>&nbsp;*detail);
</td></tr></table><br></i>
The proxy of the service is used by a client to request a piece of information and the service responds with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
HTTP/1.1 200 OK <br />
Content-Type: text/xml <br />
Content-Length: nnn <br />
<br />
&lt;SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsd="http://www.w3.org/2001/XMLSchema" <br />
&lt;SOAP-ENV:Body&#62; <br />
&lt;getInfoResponse&#62; <br />
&lt;detail&#62; <br />
&lt;picture&#62;Mona Lisa by &lt;i&#62;Leonardo da Vinci&lt;/i&#62;&lt;/picture&#62; <br />
&lt;/detail&#62; <br />
&lt;/getInfoResponse&#62; <br />
&lt;/SOAP-ENV:Body&#62; <br />
&lt;/SOAP-ENV:Envelope&#62;
</td></tr></table><br></tt>
As a result of the mixed content decoding, the <i>detail</i> string contains "<tt>&lt;picture&#62;Mona Lisa by &lt;i&#62;Leonardo da Vinci&lt;/i&#62;&lt;/picture&#62;</tt>".

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.3.6">
11.3.6</a>&nbsp;&nbsp;<font color="#0000FF">C++ Strings</font></h4><a name="sec:strings">
</a>

<div class="p"><!----></div>
gSOAP supports C++ strings <i>std::string</i> and <i>std::wstring</i> wide character strings.
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;std::string xsd__string; <br />
<b>class</b>&nbsp;ns__myClass <br />
{ <b>public</b>: <br />
&nbsp;&nbsp;&nbsp;xsd__string s; // serialized with xsi:type="xsd:string" <br />
&nbsp;&nbsp;&nbsp;std::string t; // serialized without xsi:type <br />
... <br />
};
</td></tr></table><br></i>

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution:</b></font> Please avoid mixing <i>std::string</i> and C strings (<i><b>char</b>*</i>) in the header file when using SOAP 1.1 encoding. The problem is that multi-referenced strings in SOAP encoded messages cannot be assigned simultaneously to a <i>std::string</i> and a <i><b>char</b>*</i> string.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.3.7">
11.3.7</a>&nbsp;&nbsp;<font color="#0000FF">Changing the Encoding Precision of <b>float</b>&nbsp;and <b>double</b>&nbsp;Types</font></h4>

<div class="p"><!----></div>
The <i>double</i> encoding format is by default set to "<i>%.18G</i>" (see a manual on <i>printf</i> text formatting in C),
i.e.&nbsp;at most 18 digits of precision to limit a loss in accuracy.
The <i>float</i> encoding format is by default "<i>%.9G</i>", i.e.&nbsp;at most 9 digits of precision.

<div class="p"><!----></div>
The encoding format of a double type can be set by assigning a format string to <i>soap.double_format</i>, where <i>soap</i> is a
variable that contains the
current runtime context. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); // sets double_format = "%.18G" <br />
soap.double_format = "%e"; // redefine
</td></tr></table><br></i>
which causes all doubles to be encoded in scientific notation.
Likewise, the encoding format of a float type can be set by assigning a format string to the static <i>soap_float_format</i> string variable. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); // sets float_format = "%.9G" <br />
soap.float_format = "%.4f"; // redefine
</td></tr></table><br></i>
which causes all floats to be encoded with four digits precision.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: The format strings are not automatically reset before or after
SOAP communications. An error in the format string may result in the incorrect
encoding of floating point values.

<div class="p"><!----></div>
A special case for C format string patterns is introduced in gSOAP 2.8.18. A
C format string that is used as a pattern for a typedef float or double in the
gSOAP header file is used to format the output of the floating point value in
XML. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>float</b>&nbsp;time__ratio "%5.2f";
</td></tr></table><br></i>
This will output the float with 5 digits total and 2 digits after the decimal
point.

<div class="p"><!----></div>
When <tt>xs:totalDigits</tt> and <tt>xs:fractionDigits</tt> are given in a XSD file,
then also a C format string is produced to output floating point values with
the proper precision and scale. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;simpleType name="ratio"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;restriction base="xsd:float"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;totalDigits value="5"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;fractionDigits value="2"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/restriction&#62; <br />
&lt;/simpleType&#62;
</td></tr></table><br></tt>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.3.8">
11.3.8</a>&nbsp;&nbsp;<font color="#0000FF">INF, -INF, and NaN Values of <b>float</b>&nbsp;and <b>double</b>&nbsp;Types</font></h4>

<div class="p"><!----></div>
The gSOAP runtime <i>stdsoap2.cpp</i> and header file <i>stdsoap2.h</i> support the marshalling of IEEE INF, -INF, and NaN
representations.  Under certain circumstances this may break if the hardware and/or C/C++ compiler does not support these
representations.
To remove the representations, remove the inclusion of the <i> &lt; math.h &gt; </i> header file from the <i>stdsoap2.h</i> file.
You can control the representations as well, which are defined by the macros:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#define FLT_NAN <br />
#define FLT_PINFTY <br />
#define FLT_NINFTY <br />
#define DBL_NAN <br />
#define DBL_PINFTY <br />
#define DBL_NINFTY
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.4">
11.4</a>&nbsp;&nbsp;<font color="#0000FF">Enumeration Serialization</font></h3><a name="sec:enum">
</a>

<div class="p"><!----></div>
Enumerations are generally useful for the declaration of named integer-valued constants, also called enumeration constants.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.4.1">
11.4.1</a>&nbsp;&nbsp;<font color="#0000FF">Serialization of Symbolic Enumeration Constants</font></h4>

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> tool encodes the constants of enumeration-typed variables in symbolic form using the names of the constants when possible to comply to SOAP's enumeration encoding style. Consider for example the following enumeration of weekdays:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;weekday {Mon, Tue, Wed, Thu, Fri, Sat, Sun};
</td></tr></table><br></i>
The enumeration-constant <i>Mon</i>, for example, is encoded as
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;weekday xsi:type="weekday"&#62;Mon&lt;/weekday&#62;
</td></tr></table><br></tt>
The value of the <tt>xsi:type</tt> attribute is the enumeration-type identifier's name. If the element is independent as in the example above, the element name is the enumeration-type identifier's name.

<div class="p"><!----></div>
The encoding of complex types such as enumerations requires a reference to an XML Schema through the use of a namespace prefix. The namespace prefix can be specified as part of the enumeration-type identifier's name, with the usual namespace prefix conventions for identifiers. This can be used to explicitly specify the encoding style. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;ns1__weekday {Mon, Tue, Wed, Thu, Fri, Sat, Sun};
</td></tr></table><br></i>
The enumeration-constant <i>Sat</i>, for example, is encoded as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;ns1:weekday xsi:type="ns1:weekday"&#62;Sat&lt;/ns1:weekday&#62;
</td></tr></table><br></tt>
The corresponding XML Schema for this enumeration data type would be:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:element name="weekday" type="tns:weekday"/&#62; <br />
&lt;xsd:simpleType name="weekday"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;xsd:restriction base="xsd:string"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;xsd:enumeration value="Mon"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;xsd:enumeration value="Tue"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;xsd:enumeration value="Wed"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;xsd:enumeration value="Thu"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;xsd:enumeration value="Fri"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;xsd:enumeration value="Sat"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;xsd:enumeration value="Sun"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/xsd:restriction&#62; <br />
&lt;/xsd:simpleType&#62;
</td></tr></table><br></tt>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.4.2">
11.4.2</a>&nbsp;&nbsp;<font color="#0000FF">Encoding of Enumeration Constants</font></h4>

<div class="p"><!----></div>
If the value of an enumeration-typed variable has no corresponding named constant, the value is encoded as a signed integer literal. For example, the following declaration of a <i>workday</i> enumeration type lacks named constants for Saturday and Sunday:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;ns1__workday {Mon, Tue, Wed, Thu, Fri};
</td></tr></table><br></i>
If the constant <i>5</i> (Saturday) or <i>6</i> (Sunday) is assigned to a variable of the <i>workday</i> enumeration type, the variable will be encoded with the integer literals <tt>5</tt> and <tt>6</tt>, respectively. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;ns1:workday xsi:type="ns1:workday"&#62;5&lt;/ns1:workday&#62;
</td></tr></table><br></tt>
Since this is legal in C++ and SOAP allows enumeration constants to be integer literals, this method ensures that non-symbolic
enumeration constants are correctly communicated to another party if the other party accepts literal enumeration constants (as
with the gSOAP <i>soapcpp2</i> tool).

<div class="p"><!----></div>
Both symbolic and literal enumeration constants can be decoded.

<div class="p"><!----></div>
To enforce the literal enumeration constant encoding and to get the literal constants in the WSDL file, use the following trick:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;ns1__nums { _1 = 1, _2 = 2, _3 = 3 };
</td></tr></table><br></i>
The difference with an enumeration type without a list of values and the enumeration type above is that the enumeration constants
will appear in the WSDL service description.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.4.3">
11.4.3</a>&nbsp;&nbsp;<font color="#0000FF">Initialized Enumeration Constants</font></h4>

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> compiler supports the initialization of enumeration constants, as in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;ns1__relation {LESS = -1, EQUAL = 0, GREATER = 1};
</td></tr></table><br></i>
The symbolic names <tt>LESS</tt>, <tt>EQUAL</tt>, and <tt>GREATER</tt> will appear in the SOAP payload for the encoding of the <i>ns1__relation</i> enumeration values <i>-1</i>, <i>0</i>, and <i>1</i>, respectively.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.4.4">
11.4.4</a>&nbsp;&nbsp;<font color="#0000FF">How to "Reuse" Symbolic Enumeration Constants</font></h4>

<div class="p"><!----></div>
A well-known deficiency of C and C++ enumeration types is the lack of support for the reuse of symbolic names by multiple enumerations. That is, the names of all the symbolic constants defined by an enumeration cannot be reused by another enumeration. To force encoding of the same symbolic name by different enumerations, the identifier of the symbolic name can end in an underscore (<i>_</i>) or any number of underscores to distinguish it from other symbolic names in C++. This guarantees that the SOAP encoding will use the same name, while the symbolic names can be distinguished in C++. Effectively, the underscores are removed from a symbolic name prior to encoding.

<div class="p"><!----></div>
Consider for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;ns1__workday {Mon, Tue, Wed, Thu, Fri}; <br />
<b>enum</b>&nbsp;ns1__weekday {Mon_, Tue_, Wed_, Thu_, Fri_, Sat_, Sun_};
</td></tr></table><br></i>
which will result in the encoding of the constants of <i>enum ns1__weekday</i> without the underscore, for example as <tt>Mon</tt>.

<div class="p"><!----></div>
As an alternative to the trailing underscores that can get quite long for commonly used symbolic enum names, you can use the following convention with double underscores to add the enum name to the enum constants:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;prefixedname { prefixedname__enumconst1, prefixedname__enumconst2, ... };
</td></tr></table><br></i>
where the type name of the enumeration <i>prefixedname</i> is a prefixed name,
such as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;ns1__workday {
ns1__workday__Mon,
ns1__workday__Tue,
ns1__workday__Wed,
ns1__workday__Thu,
ns1__workday__Fri }; <br />
<b>enum</b>&nbsp;ns1__weekday {
ns1__workday__Mon,
ns1__workday__Tue,
ns1__workday__Wed,
ns1__workday__Thu,
ns1__workday__Fri,
ns1__workday__Sat,
ns1__workday__Sun
}; <br />
</td></tr></table><br></i>
This ensures that the XML schema enumeration values are still simply <tt>Mon</tt>, <tt>Tue</tt>, <tt>Wed</tt>, <tt>Thu</tt>, <tt>Fri</tt>, <tt>Sat</tt>, and <tt>Sun</tt>.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: The following declaration:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;ns1__workday {Mon, Tue, Wed, Thu, Fri}; <br />
<b>enum</b>&nbsp;ns1__weekday {Sat = 5, Sun = 6};
</td></tr></table><br></i>
will not properly encode the <i>weekday</i> enumeration when you assume that workdays are part of weekdays, because it lacks the named constants for <i>workday</i> in its enumeration list. All enumerations must be self-contained and cannot use enum constants of other enumerations.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.4.5">
11.4.5</a>&nbsp;&nbsp;<font color="#0000FF">Boolean Enumeration Serialization for C</font></h4><a name="sec:boolean">
</a>

<div class="p"><!----></div>
When developing a C Web service application, the C++ <i>bool</i> type should not be used since it is not usually supported by the C compiler.
Instead, an enumeration type should be used to serialize true/false values as <tt>xsd:boolean</tt> Schema type enumeration values.
The <tt>xsd:boolean</tt> XML Schema type is defined as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;xsd__boolean {false_, true_};
</td></tr></table><br></i>
The value <i>false_</i>, for example, is encoded as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;xsd:boolean xsi:type="xsd:boolean"&#62;false&lt;/xsd:boolean&#62; <br />
</td></tr></table><br></tt>
Peculiar of the SOAP boolean type encoding is that it only defines the values <tt>0</tt> and <tt>1</tt>, while the built-in XML Schema boolean type also defines the <tt>false</tt> and <tt>true</tt> symbolic constants as valid values. The following example declaration of an enumeration type lacks named constants altogether to force encoding of the enumeration values as literal constants:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;SOAP_ENC__boolean {};
</td></tr></table><br></i>
The value <i>0</i>, for example, is encoded with an integer literal:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;SOAP-ENC:boolean xsi:type="SOAP-ENC:boolean"&#62;0&lt;SOAP-ENC:boolean&#62;
</td></tr></table><br></tt>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.4.6">
11.4.6</a>&nbsp;&nbsp;<font color="#0000FF">Bitmask Enumeration Serialization</font></h4>

<div class="p"><!----></div>
A bitmask is an enumeration of flags such as declared with C#'s [Flags] <i><b>enum</b></i> annotation.
gSOAP supports bitmask encoding and decoding for interoperability. However, bitmask types are not standardized with SOAP RPC.

<div class="p"><!----></div>
A special syntactic convention is used in the header file input to the gSOAP <i>soapcpp2</i> compiler to indicate the use of bitmasks with an
asterisk:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;* <i>name</i> { <i>enum-constant</i>, <i>enum-constant</i>, ... };
</td></tr></table><br></i>
The gSOAP <i>soapcpp2</i> compiler will encode the enumeration constants as flags, i.e. as a series of powers of 2 starting with 1.
The enumeration constants can be or-ed to form a bitvector (bitmask) which is encoded and decoded as a list of symbolic values
in SOAP.
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;* ns__machineStatus { ON, BELT, VALVE, HATCH}; <br />
<b>int</b>&nbsp;ns__getMachineStatus(<b>char</b>&nbsp;*name, <b>char</b>&nbsp;*<b>enum</b>&nbsp;ns__machineStatus result);
</td></tr></table><br></i>
Note that the use of the <i><b>enum</b></i> does not require the asterisk, only the definition.
The gSOAP <i>soapcpp2</i> compiler generates the enumeration:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>enum</b>&nbsp;ns__machineStatus { ON=1, BELT=2, VALVE=4, HATCH=8};
</td></tr></table><br></i>
A service operation implementation in a Web service can return:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__getMachineStatus(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*name, <b>enum</b>&nbsp;ns__machineStatus result) <br />
{ ... <br />
&nbsp;&nbsp;&nbsp;*result = BELT  -  HATCH; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.5">
11.5</a>&nbsp;&nbsp;<font color="#0000FF">Struct Serialization</font></h3><a name="sec:struct">
</a>

<div class="p"><!----></div>
A <i><b>struct</b></i> data type is encoded as an XML Schema complexType (SOAP-encoded compound data type) such that the
<i><b>struct</b></i> name forms the data type's element name and schema type and the
fields of the <i><b>struct</b></i> are the data type's accessors. This encoding is
identical to the <i><b>class</b></i> instance encoding without inheritance and method
declarations, see Section&nbsp;<a href="#sec:class">11.6</a> for further details.  However, the
encoding and decoding of <i><b>struct</b></i>s is more efficient compared to
<i><b>class</b></i> instances due to the lack of inheritance and the requirement by
the serialization routines to check inheritance properties at run time.

<div class="p"><!----></div>
Certain type of fields of a <i><b>struct</b></i> can be (de)serialized as XML
attributes using the <i>@</i> type qualifier.  See Section&nbsp;<a href="#sec:attributes">11.6.7</a>
for more details.

<div class="p"><!----></div>
See Section&nbsp;<a href="#sec:idtrans">10.3</a> for more details on the struct/class member field
serialization and the resulting element and attribute qualified forms.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.6">
11.6</a>&nbsp;&nbsp;<font color="#0000FF">Class Instance Serialization</font></h3><a name="sec:class">
</a>

<div class="p"><!----></div>
A <i><b>class</b></i> instance is serialized as an XML Schema complexType (SOAP-encoded compound data type) such that the
<i><b>class</b></i> name forms the data type's element name and schema type and the
data member fields are the data type's accessors. Only the data member fields
are encoded in the SOAP payload. Class methods are not encoded.

<div class="p"><!----></div>
The general form of a <i><b>class</b></i> declaration is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;<font size="+1"><span class="roman">[</span></font>namespace_prefix__<font size="+1"><span class="roman">]</span></font>class_name1 <font size="+1"><span class="roman">[</span></font>:<font size="+1"><span class="roman">[</span></font><b>public</b>:<font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font><b>private</b>:<font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font><b>protected</b>:<font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font>namespace_prefix__<font size="+1"><span class="roman">]</span></font>class_name2<font size="+1"><span class="roman">]</span></font> <br />
{ <br />
&nbsp;&nbsp;&nbsp;<font size="+1"><span class="roman">[</span></font><b>public</b>:<font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font><b>private</b>:<font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font><b>protected</b>:<font size="+1"><span class="roman">]</span></font> <br />
&nbsp;&nbsp;&nbsp;field1; <br />
&nbsp;&nbsp;&nbsp;field2; <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;<font size="+1"><span class="roman">[</span></font><b>public</b>:<font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font><b>private</b>:<font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font><b>protected</b>:<font size="+1"><span class="roman">]</span></font> <br />
&nbsp;&nbsp;&nbsp;method1; <br />
&nbsp;&nbsp;&nbsp;method2; <br />
&nbsp;&nbsp;&nbsp;... <br />
}; <br />
</td></tr></table><br></i>
where

<dl compact="compact">
 <dt><b><span class="roman"><i>namespace_prefix__</i></b></dt>
	<dd> is the optional namespace prefix of the compound data type (see identifier translation rules&nbsp;<a href="#sec:idtrans">10.3</a>)</span></dd>
 <dt><b><span class="roman"><i>class_name1</i></b></dt>
	<dd>	 is the element name of the compound data type (see identifier translation rules&nbsp;<a href="#sec:idtrans">10.3</a>).</span></dd>
 <dt><b><span class="roman"><i>class_name2</i></b></dt>
	<dd>	 is an optional base class.</span></dd>
 <dt><b><span class="roman"><i>field</i></b></dt>
	<dd>	 is a field declaration (data member). A field MAY be declared <i><b>static</b></i> and <i><b>const</b></i> and MAY be initialized.</span></dd>
 <dt><b><span class="roman"><i>method</i></b></dt>
	<dd> is a method declaration. A method MAY be declared <i><b>virtual</b></i>, but abstract methods are not allowed. The method parameter declarations are REQUIRED to have parameter identifier names.</span></dd>
 <dt><b><font size="+1"><span class="roman">[</span></font><b>public</b>:<font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font><b>private</b>:<font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font><b>protected</b>:<font size="+1"><span class="roman">]</span></font></b></dt>
	<dd> are OPTIONAL. Only members with <i><b>public</b></i> acces permission can be serialized.</dd>
</dl>
A class name is REQUIRED to be unique and cannot have the same name as a
<i><b>struct</b></i>, <i><b>enum</b></i>, or service operation name specified in the header file
input to the gSOAP <i>soapcpp2</i> compiler.  The reason is that service operation requests are
encoded similarly to class instances in SOAP and they are in principle
undistinguishable (the method parameters are encoded just as the fields of a
<i><b>class</b></i>).

<div class="p"><!----></div>
Only single inheritance is supported by the gSOAP <i>soapcpp2</i> compiler. Multiple
inheritance is not supported, because of the limitations of the SOAP protocol.

<div class="p"><!----></div>
If a constructor method is present, there MUST also be a constructor
declaration with empty parameter list.

<div class="p"><!----></div>
Classes should be declared "volatile" if you don't want gSOAP to add serialization methods to these classes, see Section&nbsp;<a href="#sec:volatile">19.4</a> for more details.

<div class="p"><!----></div>
Class templates are not supported by the gSOAP <i>soapcpp2</i> compiler, but you can use STL containers,
see Section&nbsp;<a href="#sec:templates">11.11.8</a>. You can also define your own
containers similar to STL containers.

<div class="p"><!----></div>
Certain type of fields of a <i><b>struct</b></i> can be (de)serialized as XML
attributes using the <i>@</i> type qualifier.  See Section&nbsp;<a href="#sec:attributes">11.6.7</a>
for more details.

<div class="p"><!----></div>
See Section&nbsp;<a href="#sec:idtrans">10.3</a> for more details on the struct/class member field
serialization and the resulting element and attribute qualified forms.

<div class="p"><!----></div>
Arrays may be embedded within a class (and struct) using a pointer field and
size information, see Section&nbsp;<a href="#sec:list">11.11.7</a>. This defines what is sometimes
referred to in SOAP as "generics".

<div class="p"><!----></div>
Void pointers may be used in a class (or struct), but you have to add a type
field so the gSOAP runtime can determine the type of object pointed to, see
Section&nbsp;<a href="#sec:void">11.9</a>.

<div class="p"><!----></div>
A <i><b>class</b></i> instance is encoded as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>class-name xsi:type="<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>class-name"&#62; <br />
&lt;basefield-name1 xsi:type="..."&#62;...&lt;/basefield-name1&#62; <br />
&lt;basefield-name2 xsi:type="..."&#62;...&lt;/basefield-name2&#62; <br />
... <br />
&lt;field-name1 xsi:type="..."&#62;...&lt;/field-name1&#62; <br />
&lt;field-name2 xsi:type="..."&#62;...&lt;/field-name2&#62; <br />
... <br />
&lt;/<font size="+1"><span class="roman">[</span></font>namespace-prefix:<font size="+1"><span class="roman">]</span></font>class-name&#62;
</td></tr></table><br></tt>
where the <tt>field-name</tt> accessors have element-name representations of the
class fields and the <tt>basefield-name</tt> accessors have element-name
representations of the base class fields. (The optional parts resulting from
the specification are shown enclosed in <font size="+1"><span class="roman">[</span></font><font size="+1"><span class="roman">]</span></font>.)

<div class="p"><!----></div>
The decoding of a class instance allows any ordering of the accessors in the
SOAP payload. However, if a base class field name is identical to a derived
class field name because the field is overloaded, the base class field name
MUST precede the derived class field name in the SOAP payload for decoding.
gSOAP guarantees this, but interoperability with other SOAP implementations is
cannot be guaranteed.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.6.1">
11.6.1</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4>

<div class="p"><!----></div>
The following example declares a base class <i>ns__Object</i> and a derived class <i>ns__Shape</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "shape.h": <br />
<b>class</b>&nbsp;ns__Object <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
}; <br />
<b>class</b>&nbsp;ns__Shape : <b>public</b>&nbsp;ns__Object <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;sides; <br />
&nbsp;&nbsp;&nbsp;<b>enum</b>&nbsp;ns__Color {Red, Green, Blue} color; <br />
&nbsp;&nbsp;&nbsp;ns__Shape(); <br />
&nbsp;&nbsp;&nbsp;ns__Shape(<b>int</b>&nbsp;sides, <b>enum</b>&nbsp;ns__Green color); <br />
&nbsp;&nbsp;&nbsp;~ns__Shape(); <br />
};
</td></tr></table><br></i>
The implementation of the methods of <i><b>class</b>&nbsp;ns__Shape</i> must not be part of the header file and need to be defined elsewhere.

<div class="p"><!----></div>
An instance of <i><b>class</b>&nbsp;ns__Shape</i> with name Triangle, 3 sides, and color Green is encoded as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;ns:Shape xsi:type="ns:Shape"&#62; <br />
&lt;name xsi:type="string"&#62;Triangle&lt;/name&#62; <br />
&lt;sides xsi:type="int"&#62;3&lt;/sides&#62; <br />
&lt;color xsi:type="ns:Color"&#62;Green&lt;/color&#62; <br />
&lt;/ns:shape&#62;
</td></tr></table><br></tt>
The namespace URI of the namespace prefix <tt>ns</tt> must be defined by a namespace mapping table, see Section&nbsp;<a href="#sec:nstable">10.4</a>.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.6.2">
11.6.2</a>&nbsp;&nbsp;<font color="#0000FF">Initialized <b>static</b>&nbsp;<b>const</b>&nbsp;Fields</font></h4>

<div class="p"><!----></div>
A data member field of a class declared as <i><b>static</b>&nbsp;<b>const</b></i> is initialized
with a constant value at compile time. This field is encoded in the
serialization process, but is not decoded in the deserialization process. For
example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "triangle.h": <br />
<b>class</b>&nbsp;ns__Triangle : <b>public</b>&nbsp;ns__Object <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;size; <br />
&nbsp;&nbsp;&nbsp;<b>static</b>&nbsp;<b>const</b>&nbsp;<b>int</b>&nbsp;sides = 3; <br />
};
</td></tr></table><br></i>
An instance of <i><b>class</b>&nbsp;ns__Triangle</i> is encoded in SOAP as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;ns:Triangle xsi:type="ns:Triangle"&#62; <br />
&lt;name xsi:type="string"&#62;Triangle&lt;/name&#62; <br />
&lt;size xsi:type="int"&#62;15&lt;/size&#62; <br />
&lt;sides xsi:type="int"&#62;3&#62;/sides&#62; <br />
&lt;/ns:Triangle&#62;
</td></tr></table><br></tt>
Decoding will ignore the <i>sides</i> field's value.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: The current gSOAP implementation does not support encoding
<i><b>static</b>&nbsp;<b>const</b></i> fields, due to C++ compiler compatibility differences.
This feature may be provided the future.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.6.3">
11.6.3</a>&nbsp;&nbsp;<font color="#0000FF">Class Methods</font></h4>

<div class="p"><!----></div>
A <i><b>class</b></i> declaration in the header file input to the gSOAP <i>soapcpp2</i> compiler MAY
include method declarations.  The method implementations MUST NOT be part of
the header file but are required to be defined in another C++ source that is
externally linked with the application. This convention is also used for the
constructors and destructors of the <i><b>class</b></i>.

<div class="p"><!----></div>
Dynamic binding is supported, so a method MAY be declared <i><b>virtual</b></i>.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.6.4">
11.6.4</a>&nbsp;&nbsp;<font color="#0000FF">Getter and Setter Methods</font></h4><a name="sec:gettersetter">
</a>

<div class="p"><!----></div>
Setter and getter methods are invoked at run time upon serialization and
deserialization of class instances, respectively. The use of setter and getter methods adds more flexibility to the serialization and deserialization process.

<div class="p"><!----></div>
A setter method is called in the serialization phase from the virtual
<i>soap_serialization</i> method generated by the gSOAP <i>soapcpp2</i> compiler.  You can use
setter methods to process a class instance just before it is serialized. A
setter method can be used to convert application data, such as translating
transient application data into serializable data, for example. You can also
use setter methods to retrieve dynamic content and use it to update a class
instance right before serialization. Remember setters
as "set to serialize" operations.

<div class="p"><!----></div>
Getter methods are invoked after deserialization of the instance. You can use
them to adjust the contents of class instances after all their members have been
deserialized. Getters can be used to convert deserialized members into
transient members and even invoke methods to process the deserialized data on
the fly.

<div class="p"><!----></div>
Getter and setter methods have the following signature:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<font size="+1"><span class="roman">[</span></font><b>virtual</b><font size="+1"><span class="roman">]</span></font> <b>int</b>&nbsp;get(<b>struct</b>&nbsp;soap *soap) <font size="+1"><span class="roman">[</span></font><b>const</b><font size="+1"><span class="roman">]</span></font>; <br />
<font size="+1"><span class="roman">[</span></font><b>virtual</b><font size="+1"><span class="roman">]</span></font> <b>int</b>&nbsp;set(<b>struct</b>&nbsp;soap *soap);
</td></tr></table><br></i>
The active soap struct will be passed to the <i>get</i> and <i>set</i> methods. The methods should return <i>SOAP_OK</i> when successful. A setter method should prepare the contents of the class instance for serialization. A getter method should process the instance after deserialization.

<div class="p"><!----></div>
Here is an example of a base64 binary class:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;xsd__base64Binary <br />
{ <b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>char *__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>__size; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;get(struct soap *soap); <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;set(struct soap *soap); <br />
};
</td></tr></table><br></i>
Suppose that the type and options members of the attachment should be set when
the class is about to be serialized. This can be accomplished with the
<i>set</i> method from the information provided by the <i>__ptr</i> to the data
and the soap struct passed to the <i>set</i> method (you can pass data via the
<i><b>void</b>*soap.user</i> field).

<div class="p"><!----></div>
The <i>get</i> method is invoked after the base64 data has been processed. You
can use it for post-processing purposes.

<div class="p"><!----></div>
Here is another example. It defines a primitive <i>update</i> type. The class is a wrapper for the <i>time_t</i> type, see Section&nbsp;<a href="#sec:primclass">11.3.2</a>. Therefore, elements of this type contain <tt>xsd:dateType</tt> data.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;update <br />
{ <b>public</b>: <br />
&nbsp;&nbsp;&nbsp;time_t __item; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;set(<b>struct</b>&nbsp;soap *soap); <br />
};
</td></tr></table><br></i>
The setter method assigns the current time:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;update::set(<b>struct</b>&nbsp;soap *soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;this<tt>-&gt;</tt>__item = time(NULL); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
Therefore, serialization results in the inclusion of a time stamp in XML.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: a <i>get</i> method is invoked only when the XML element with its data
was completely parsed. The method is not invoked when the element is an <tt>xsi:nil</tt> element or has an 
<tt>href</tt> attribute.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution:</b></font> The <i>soap_serialize</i> method of a class calls the setter (when
provided). However, the <i>soap_serialize</i> method is declared <i><b>const</b></i>
while the setter should be allowed to modify the contents of the class
instance. Therefore, the gSOAP-generated code recasts the instance and the
<i><b>const</b></i> is removed when invoking the setter.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.6.5">
11.6.5</a>&nbsp;&nbsp;<font color="#0000FF">Streaming XML with Getter and Setter Methods</font></h4><a name="sec:streaming">
</a>

<div class="p"><!----></div>
Getter methods enable streaming XML operations. A getter method is invoked
when the object is deserialized and the rest of the SOAP/XML message has not
been processed yet. For example, you can add a getter method to the SOAP Header
class to implement header processing logic that is activated as soon as the
SOAP Header is received.  An example code is shown below:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;h__Authentication <br />
{ <b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*id; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;get(<b>struct</b>&nbsp;soap *soap); <br />
}; <br />
<b>class</b>&nbsp;SOAP_ENV__Header <br />
{ <b>public</b>: <br />
&nbsp;&nbsp;&nbsp;h__Authentication *h__authentication; <br />
};
</td></tr></table><br></i>
The <i>Authentication</i> SOAP Header field is instantiated and decoded. After
decoding, the getter method is invoked, which can be used to check the <i>id</i>
before the rest of the SOAP message is processed.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.6.6">
11.6.6</a>&nbsp;&nbsp;<font color="#0000FF">Polymorphism, Derived Classes, and Dynamic Binding</font></h4><a name="sec:polymorph">
</a>

<div class="p"><!----></div>
Interoperability between client and service applications developed with gSOAP
is established even when clients and/or services use derived classes instead of
the base classes used in the declaration of the service operation parameters.  A
client application MAY use pointers to instances of derived classes for the
input parameters of a service operation. If the service was compiled with a
declaration and implementation of the derived class, the service operation base
class input parameters are demarshalled and a derived class instance is created
instead of a base class instance. If the service did not include a declaration
of the derived class, the derived class fields are ignored and a base class
instance is created. Therefore, interoperability is guaranteed even when the
client sends an instance of a derived classes and when a service returns an
instance of a derived class.

<div class="p"><!----></div>
The following example declares Base and Derived classes and a service operation
that takes a pointer to a Base class instance and returns a Base class
instance:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "derived.h" <br />
<b>class</b>&nbsp;Base <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;Base(); <br />
&nbsp;&nbsp;&nbsp;<b>virtual</b>&nbsp;<b>void</b>&nbsp;print(); <br />
}; <br />
<b>class</b>&nbsp;Derived : <b>public</b>&nbsp;Base <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;num; <br />
&nbsp;&nbsp;&nbsp;Derived(); <br />
&nbsp;&nbsp;&nbsp;<b>virtual</b>&nbsp;<b>void</b>&nbsp;print(); <br />
}; <br />
<b>int</b>&nbsp;method(Base *in, <b>struct</b>&nbsp;methodResponse { Base *out; } &amp;result);
</td></tr></table><br></i>
This header file specification is processed by the gSOAP <i>soapcpp2</i> compiler to produce the stub and skeleton routines which are used to implement a client and service.
The pointer of the service operation is also allowed to point to Derived class instances and these instances will be marshalled as Derived class instances and send to a service, which is in accord to the usual semantics of parameter passing in C++ with dynamic binding.

<div class="p"><!----></div>
The Base and Derived class method implementations are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Method implementations of the Base and Derived classes: <br />
#include "soapH.h" <br />
... <br />
Base::Base() <br />
{ <br />
&nbsp;&nbsp;&nbsp;cout  &lt;&lt;  "created a Base class instance"  &lt;&lt;  endl; <br />
} <br />
Derived::Derived() <br />
{<br />
&nbsp;&nbsp;&nbsp;cout  &lt;&lt;  "created a Derived class instance"  &lt;&lt;  endl; <br />
} <br />
Base::print() <br />
{ <br />
&nbsp;&nbsp;&nbsp;cout  &lt;&lt;  "print(): Base class instance "  &lt;&lt;  name  &lt;&lt;  endl; <br />
} <br />
Derived::print() <br />
{ <br />
&nbsp;&nbsp;&nbsp;cout  &lt;&lt;  "print(): Derived class instance "  &lt;&lt;  name  &lt;&lt;  " "  &lt;&lt;  num  &lt;&lt;  endl; <br />
}
</td></tr></table><br></i>
Below is an example <i>CLIENT</i> application that creates a Derived class instance that is passed as the input parameter of the service operation:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// CLIENT <br />
#include "soapH.h" <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;Derived obj1; <br />
&nbsp;&nbsp;&nbsp;Base *obj2; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;methodResponse r; <br />
&nbsp;&nbsp;&nbsp;obj1.name = "X"; <br />
&nbsp;&nbsp;&nbsp;obj1.num = 3; <br />
&nbsp;&nbsp;&nbsp;soap_call_method(&amp;soap, url, action, &amp;obj1, r); <br />
&nbsp;&nbsp;&nbsp;r.obj2<tt>-&gt;</tt>print(); <br />
} <br />
...
</td></tr></table><br></i>
The following example <i>SERVER1</i> application copies a class instance (Base or Derived class) from the input to the output parameter:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// SERVER1 <br />
#include "soapH.h" <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_serve(soap_new()); <br />
} <br />
<b>int</b>&nbsp;method(<b>struct</b>&nbsp;soap *soap, Base *obj1, <b>struct</b>&nbsp;methodResponse &amp;result) <br />
{ <br />
&nbsp;&nbsp;&nbsp;obj1<tt>-&gt;</tt>print(); <br />
&nbsp;&nbsp;&nbsp;result.obj2 = obj1; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
...
</td></tr></table><br></i>
The following messages are produced by the <i>CLIENT</i> and <i>SERVER1</i> applications:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
CLIENT: created a Derived class instance <br />
SERVER1: created a Derived class instance <br />
SERVER1: print(): Derived class instance X 3 <br />
CLIENT: created a Derived class instance <br />
CLIENT: print(): Derived class instance X 3
</td></tr></table><br></span>
Which indicates that the derived class kept its identity when it passed through <i>SERVER1</i>. Note that instances are created both by the <i>CLIENT</i> and <i>SERVER1</i> by the demarshalling process.

<div class="p"><!----></div>
Now suppose a service application is developed that only accepts Base class instances. The header file is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "base.h": <br />
<b>class</b>&nbsp;Base <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;Base(); <br />
&nbsp;&nbsp;&nbsp;<b>virtual</b>&nbsp;<b>void</b>&nbsp;print(); <br />
}; <br />
<b>int</b>&nbsp;method(Base *in, Base *out);
</td></tr></table><br></i>
This header file specification is processed by the gSOAP <i>soapcpp2</i> tool to produce skeleton routine which is used to implement a service (so the client will still use the derived classes).

<div class="p"><!----></div>
The method implementation of the Base class are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Method implementations of the Base class: <br />
#include "soapH.h" <br />
... <br />
Base::Base() <br />
{ <br />
&nbsp;&nbsp;&nbsp;cout  &lt;&lt;  "created a Base class instance"  &lt;&lt;  endl; <br />
} <br />
Base::print() <br />
{ <br />
&nbsp;&nbsp;&nbsp;cout  &lt;&lt;  "print(): Base class instance "  &lt;&lt;  name  &lt;&lt;  endl; <br />
} <br />
</td></tr></table><br></i>
And the <i>SERVER2</i> application is that uses the Base class is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// SERVER2 <br />
#include "soapH.h" <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_serve(soap_new()); <br />
} <br />
<b>int</b>&nbsp;method(<b>struct</b>&nbsp;soap *soap, Base *obj1, <b>struct</b>&nbsp;methodResponse &amp;result) <br />
{ <br />
&nbsp;&nbsp;&nbsp;obj1<tt>-&gt;</tt>print(); <br />
&nbsp;&nbsp;&nbsp;result.obj2 = obj1; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
...
</td></tr></table><br></i>
Here are the messages produced by the <i>CLIENT</i> and <i>SERVER2</i> applications:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
CLIENT: created a Derived class instance <br />
SERVER2: created a Base class instance <br />
SERVER2: print(): Base class instance X <br />
CLIENT: created a Base class instance <br />
CLIENT: print(): Base class instance X
</td></tr></table><br></span>
In this example, the object was passed as a Derived class instance to <i>SERVER2</i>. Since <i>SERVER2</i> only implements the Base class, this object is converted to a Base class instance and send back to <i>CLIENT</i>.

<div class="p"><!----></div>
	      <h4><a name="tth_sEc11.6.7">
11.6.7</a>&nbsp;&nbsp;<font color="#0000FF">XML Attributes</font></h4><a name="sec:attributes">
</a>

<div class="p"><!----></div>
The SOAP RPC/LIT and SOAP DOC/LIT encoding styles support XML attributes in
SOAP messages while SOAP RPC with "Section 5" encoding does not support XML
attributes other than the SOAP and XSD specific attributes. SOAP RPC "Section
5" encoding has advantages for cross-language interoperability and data
encodings such as graph serialization. However, RPC/LIT and DOC/LIT enables
direct exchange of XML documents, which may include encoded application data
structures. Language interoperability is compromised, because no mapping
between XML and the typical language data types is defined. The meaning of the
RPC/LIT and DOC/LIT XML content is Schema driven rather than
application/language driven.

<div class="p"><!----></div>
gSOAP supports XML attribute (de)serialization of members in structs and classes.
Attributes are primitive XSD types, such as strings, enumerations, boolean, and
numeric types. To declare an XML attribute in a struct/class, the qualifier
<i>@</i> is used with the type of the attribute. The type must be
primitive type (including enumerations and strings), which can be declared with or without
a <i><b>typedef</b></i> to associate a XSD type with the C/C+ type.  For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string; <br />
<b>typedef</b>&nbsp;<b>bool</b>&nbsp;*xsd__boolean; <br />
<b>enum</b>&nbsp;ns__state { _0, _1, _2 }; <br />
<b>struct</b>&nbsp;ns__myStruct <br />
{ <br />
&nbsp;&nbsp;&nbsp;@xsd__string ns__type; // encode as XML attribute 'ns:type' of type 'xsd:string' <br />
&nbsp;&nbsp;&nbsp;@xsd__boolean ns__flag = false; // encode as XML attribute 'ns:flag' of type 'xsd:boolean' <br />
&nbsp;&nbsp;&nbsp;@<b>enum</b>&nbsp;ns__state ns__state = _2; // encode as XML attribute 'ns:state' of type 'ns:state' <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;ns__myStruct *next; <br />
};
</td></tr></table><br></i>
The <i>@</i> qualifier indicates XML attribute encoding for the
<i>ns__type</i>, <i>ns__flag</i>, and <i>ns__state</i> fields. Note that the
namespace prefix <i>ns</i> is used to distinguish these attributes from any
other attributes such as <tt>xsi:type</tt> (<tt>ns:type</tt> is not to be confused
with <tt>xsi:type</tt>).

<div class="p"><!----></div>
Default values can be associated with any field that has
a primitive type in a struct/class, as is illustrated in this example. The
default values are used when the receiving message does not contain the
corresponding values.

<div class="p"><!----></div>
String attributes are optional. Other type of attributes should be declared as pointers to make them optional:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__myStruct <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>int</b>&nbsp;*a; // omitted when NULL <br />
};
</td></tr></table><br></i>
Because a service operation request and response is essentially a struct, XML
attributes can also be associated with method requests and responses. For
example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__myMethod(@<b>char</b>&nbsp;*ns__name, ...);
</td></tr></table><br></i>
Attributes can also be attached to the dynamic arrays, binary types, and wrapper classes/structs of primitive
types. Wrapper classes are described in Section&nbsp;<a href="#sec:primclass">11.3.2</a>.  For
example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;xsd__string <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*__item; <br />
&nbsp;&nbsp;&nbsp;@xsd__boolean flag; <br />
};
</td></tr></table><br></i>
and
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;xsd__base64Binary <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
&nbsp;&nbsp;&nbsp;@xsd__boolean flag; <br />
};
</td></tr></table><br></i>
The attribute declarations MUST follow the <i>__item</i>, <i>__ptr</i>, and <i>__size</i> fields
which define the characteristics of wrapper structs/classes and dynamic arrays.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: Do not use XML attributes with SOAP RPC encoding. You can only use attributes with RPC literal encoding.

<div class="p"><!----></div>
	      <h4><a name="tth_sEc11.6.8">
11.6.8</a>&nbsp;&nbsp;<font color="#0000FF">QName Attributes and Elements</font></h4>

<div class="p"><!----></div>
gSOAP ensures the proper decoding of XSD QNames.
An element or attribute with type QName (Qualified Name) contains a namespace prefix and a local name.
You can declare a QName type as a <i><b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__QName</i>. Values of type QName
are internally handled as regular strings.
gSOAP takes care of the proper namespace prefix mappings when deserializing QName values.
For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__QName; <br />
<b>struct</b>&nbsp;ns__myStruct <br />
{ <br />
&nbsp;&nbsp;&nbsp;xsd__QName elt = "ns:xyz"; // QName element with default value "ns:xyz" <br />
&nbsp;&nbsp;&nbsp;@xsd__QName att = "ns:abc"; // QName attribute with default value "ns:abc" <br />
};
</td></tr></table><br></i>
When the <i>elt</i> and <i>att</i> fields are serialized,
their string contents are just transmitted (which means that the application is responsible to
ensure proper formatting of the QName strings prior to transmission). When the
fields are deserialized however, gSOAP takes care mapping the qualifiers to the
appropriate namespace prefixes. Suppose that the inbound value
for the <i>elt</i> is <tt>x:def</tt>, where the namespace name associated with the
prefix <tt>x</tt> matches the namespace name of the prefix <tt>ns</tt> (as defined in
the namespace mapping table). Then, the value is automatically converted into <tt>ns:def</tt>.
If the namespace name is not in the table, then
<tt>x:def</tt> is converted to <i>"URI":def</i> where <tt>"URI"</tt> is the namespace
URI bound to <tt>x</tt> in the message received.  This enables an application to
retrieve the namespace information, whether it is in the namespace mapping
table or not.

<div class="p"><!----></div>
Note: <i>QName</i> is a pre-defined typedef type and used by gSOAP to
(de)serialize SOAP Fault codes which are QName elements.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.7">
11.7</a>&nbsp;&nbsp;<font color="#0000FF">Union Serialization</font></h3><a name="sec:union">
</a>

<div class="p"><!----></div>
A <i><b>union</b></i> is only serialized if the <i><b>union</b></i> is used within a
<i><b>struct</b></i> or <i><b>class</b></i> declaration that includes a <i><b>int</b>&nbsp;__union</i>
field that acts as a <em>discriminant</em> or <em>selector</em> for the <i><b>union</b></i>
fields. The selector stores run-time usage information about the <i><b>union</b></i>
fields. That is, the selector is used to enumerate the <i><b>union</b></i> fields such
that the gSOAP engine is able to select the correct <i><b>union</b></i> field to
serialize.

<div class="p"><!----></div>
A <i><b>union</b></i> within a <i><b>struct</b></i> or <i><b>class</b></i> with a selector field
represents <tt>xs:choice</tt> within a Schema complexType component. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__PO <br />
{ ... }; <br />
<b>struct</b>&nbsp;ns__Invoice <br />
{ ... }; <br />
<b>union</b>&nbsp;ns__PO_or_Invoice <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;ns__PO po; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;ns__Invoice invoice; <br />
}; <br />
<b>struct</b>&nbsp;ns__composite <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__union; <br />
&nbsp;&nbsp;&nbsp;<b>union</b>&nbsp;ns__PO_or_Invoice value; <br />
};
</td></tr></table><br></i>
The <i><b>union</b>&nbsp;ns__PO_or_Invoice</i> is expanded as a <tt>xs:choice</tt>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;complexType name="composite"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;sequence&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="name" type="xsd:string"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;choice&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="po" type="ns:PO"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="invoice" type="ns:Invoice"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/choice&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/sequence&#62; <br />
&lt;/complexType&#62;
</td></tr></table><br></tt>
Therefore, the name of the <i><b>union</b></i> and field can be freely chosen.
However, the <i><b>union</b></i> name should be qualified (as shown in the example) to
ensure instances of XML Schemas with <tt>elementFormDefault="qualified"</tt> are
correctly serialized (<i>po</i> and <i>invoice</i> are <tt>ns:</tt> qualified).

<div class="p"><!----></div>
The <i><b>int</b>&nbsp;__union</i> field selector's values are determined by the
<i>soapcpp2</i> compiler. Each <i><b>union</b></i> field name has a selector value
formed by:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
SOAP_UNION_<i>union-name</i>_<i>field-name</i>
</td></tr></table><br></i>
These selector values enumerate the <i><b>union</b></i> fields starting with 1. The
value 0 (or any negative value) can be assigned to omit the serialization of the <i><b>union</b></i>, but only
if explicitly allowed by validation rules, which requires <tt>minOccurs="0"</tt>
for the <tt>xs:choice</tt> as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__composite <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__union 0; // <tt>&lt;choice minOccurs="0"&#62;</tt> <br />
&nbsp;&nbsp;&nbsp;<b>union</b>&nbsp;ns__PO_or_Invoice value; <br />
};
</td></tr></table><br></i>
This way we can treat the <i><b>union</b></i> as an optional data item by setting <i>__union=0</i>.

<div class="p"><!----></div>
Since 2.7.16 it is also possible to use a '<i>$</i>' as a special marker to annotate a
selector field that must be of type <i><b>int</b></i> and the field name is no longer
relevant:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__composite <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;$<b>int</b>&nbsp;select 0; // <tt>&lt;choice minOccurs="0"&#62;</tt> <br />
&nbsp;&nbsp;&nbsp;<b>union</b>&nbsp;ns__PO_or_Invoice value; <br />
};
</td></tr></table><br></i>

<div class="p"><!----></div>
The following example shows how the <i><b>struct</b>&nbsp;ns__composite</i> instance is
initialized for serialization using the above declaration:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__composite data; <br />
data.name = "..."; <br />
data.select = SOAP_UNION_ns__PO_or_Invoice_po; // select PO <br />
data.value.po.number = ...; // populate the PO
</td></tr></table><br></i>
Note that failing to set the selector to a valid <i><b>union</b></i> field can lead to
a crash of the gSOAP serializer because it will attempt to serialize an invalid
<i><b>union</b></i> field.

<div class="p"><!----></div>
For deserialization of <i><b>union</b></i> types, the selector will be
set to one of the
<i><b>union</b></i> field selector values, as determined by the XML payload.
The selector will be set to 0 or -1 when no union member was deserialized,
where a negative value indicates that a member was required by validation rules.
Strict validation enabled with <i>SOAP_XML_STRICT</i> results in a validation fault.

<div class="p"><!----></div>
When more than one <i><b>union</b></i> is used in a <i><b>struct</b></i> or <i><b>class</b></i>, the
<i>__union</i> selectors must be renamed to avoid name clashes by using
suffixes as in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__composite <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;$<b>int</b>&nbsp;sel_value; // = SOAP_UNION_ns__PO_or_Invoice_[po - invoice] <br />
&nbsp;&nbsp;&nbsp;<b>union</b>&nbsp;ns__PO_or_Invoice value; <br />
&nbsp;&nbsp;&nbsp;$<b>int</b>&nbsp;sel_data; // = SOAP_UNIO_ns__Email_or_Fax_[email - fax] <br />
&nbsp;&nbsp;&nbsp;<b>union</b>&nbsp;ns__Email_or_Fax data; <br />
};
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.8">
11.8</a>&nbsp;&nbsp;<font color="#0000FF">Serializing Pointer Types</font></h3><a name="sec:pointer">
</a>

<div class="p"><!----></div>
The serialization of a pointer to a data type amounts to the serialization of
the data type in SOAP and the SOAP encoded representation of a pointer to the
data type is indistinguishable from the encoded representation of the data
type pointed to.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.8.1">
11.8.1</a>&nbsp;&nbsp;<font color="#0000FF">Multi-Referenced Data</font></h4>

<div class="p"><!----></div>
A data structure pointed to by more than one pointer is serialized as SOAP
multi-reference data. This means that the data will be serialized only once and
identified with a unique <tt>id</tt> attribute. The encoding of the pointers to
the shared data is done through the use of <tt>href</tt> or <tt>ref</tt> attributes
to refer to the multi-reference data. See Section&nbsp;<a href="#sec:flags">9.12</a> on
options to control the serialization of multi-reference data. To turn multi-ref off, use <i>SOAP_XML_TREE</i> to process plain tree-based XML. To completely eliminate multi-ref (de)serialization use the <i>WITH_NOIDREF</i> compile-time flag to permanently disable id-href processing. Cyclic C/C++
data structures are encoded with multi-reference SOAP encoding.  Consider for
example the following a linked list data structure:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string; <br />
<b>struct</b>&nbsp;ns__list<br />
{ <br />
&nbsp;&nbsp;&nbsp;xsd__string value; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;ns__list *next; <br />
};
</td></tr></table><br></i>
Suppose a cyclic linked list is created. The first node contains the value "<tt>abc</tt>" and points to a node with value
"<tt>def</tt>" which in turn points to the first node. This is encoded as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;ns:list id="1" xsi:type="ns:list"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;value xsi:type="xsd:string"&#62;abc&lt;/value&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;next xsi:type="ns:list"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;value xsi:type="xsd:string"&#62;def&lt;/value&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;next href="#1"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/next&#62; <br />
&lt;/ns:list&#62;
</td></tr></table><br></tt>
In case multi-referenced data is received that "does not fit in a pointer-based structure", the data is copied.
For example, the following two <i><b>struct</b></i>s are similar, except that the first uses pointer-based fields while the other uses
non-pointer-based fields:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>long</b>&nbsp;xsd__int; <br />
<b>struct</b>&nbsp;ns__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;xsd__int *a; <br />
&nbsp;&nbsp;&nbsp;xsd__int *b; <br />
} P; <br />
<b>struct</b>&nbsp;ns__record<br />
{ <br />
&nbsp;&nbsp;&nbsp;xsd__int a; <br />
&nbsp;&nbsp;&nbsp;xsd__int b; <br />
} R; <br />
... <br />
&nbsp;&nbsp;&nbsp;P.a = &amp;n; <br />
&nbsp;&nbsp;&nbsp;P.b = &amp;n; <br />
...
</td></tr></table><br></i>
Since both <i>a</i> and <i>b</i> fields of <i>P</i> point to the same integer, the encoding of <i>P</i> is multi-reference:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;ns:record xsi:type="ns:record"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;a href="#1"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;b href="#1"/&#62; <br />
&lt;/ns:record&#62; <br />
&lt;id id="1" xsi:type="xsd:int"&#62;123&lt;/id&#62;
</td></tr></table><br></tt>
Now, the decoding of the content in the <i>R</i> data structure that does not use pointers to integers results in a copy of each
multi-reference integer.  Note that the two <i><b>struct</b></i>s resemble the same XML data type because the trailing underscore will be
ignored in XML encoding and decoding.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.8.2">
11.8.2</a>&nbsp;&nbsp;<font color="#0000FF">NULL Pointers and Nil Elements</font></h4>

<div class="p"><!----></div>
A <i>NULL</i> pointer is <b>not</b> serialized, unless the pointer itself is pointed to by another pointer (but see
Section&nbsp;<a href="#sec:flags">9.12</a> to control the serialization of NULLs).
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;X <br />
{<br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;*p; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;**q; <br />
}
</td></tr></table><br></i>
Suppose pointer <i>q</i> points to pointer <i>p</i> and suppose <i>p=NULL</i>.
In that case the <i>p</i> pointer is serialized as
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;... id="123" xsi:nil="true"/&#62;
</td></tr></table><br></tt>
and the serialization of <i>q</i> refers to <tt>href="#123"</tt>.
Note that SOAP 1.1 does not support
pointer to pointer types (!), so this encoding is specific to gSOAP. The pointer to pointer encoding is rarely used in codes
anyway.  More common is a pointer to a data type such as a <i><b>struct</b></i> with pointer fields.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: When the deserializer encounters an XML element that has a <tt>xsi:nil="true"</tt> attribute but the corresponding C++ data is not a pointer or reference,
the deserializer will terminate with a <i>SOAP_NULL</i> fault when the <i>SOAP_XML_STRICT</i> flag is set.
The types section of a WSDL description contains information on the "nilability" of data.

<div class="p"><!----></div>
		     <h3><a name="tth_sEc11.9">
11.9</a>&nbsp;&nbsp;<font color="#0000FF">Void Pointers</font></h3><a name="sec:void">
</a>

<div class="p"><!----></div>
In general, void pointers (<i><b>void</b>*</i>) cannot be (de)serialized because the
type of data referred to is untyped.  To enable the (de)serialization of the
void pointers that are members of structs or classes, you can insert a
<i><b>int</b>&nbsp;__type</i> field right before the void pointer field.  The <i><b>int</b>&nbsp;__
type</i> field contains run time information on the type of the data pointed to by
<i><b>void</b>*</i> member in a struct/class to enable the (de)serialization of this
data.  The <i><b>int</b>&nbsp;__type</i> field is set to a <i>SOAP_TYPE_X</i> value, where <i>X</i> is the name of a type.  gSOAP generates the <i>SOAP_TYPE_X</i> definitions in <i>soapH.h</i> and uses them internally to uniquely identify the type of each object.
The type naming conventions outlined in
Section&nbsp;<a href="#sec:serialize">7.5.3</a> are used to determine the type name for <i>X</i>.

<div class="p"><!----></div>
Here is an example to illustrate the (de)serialization of a <i><b>void</b>*</i> field in a struct:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;myStruct <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__type; // the SOAP_TYPE pointed to by p <br />
&nbsp;&nbsp;&nbsp;<b>void</b>&nbsp;*p; <br />
};
</td></tr></table><br></i>
The <i>__type</i> integer can be set to 0 at run time to omit the serialization
of the void pointer field.

<div class="p"><!----></div>
The following example illustrates the initialization of <i>myStruct</i> with a
void pointer to an int:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;myStruct S; <br />
<b>int</b>&nbsp;n; <br />
S.p = &amp;n; <br />
S.__type = SOAP_TYPE_int; <br />
</td></tr></table><br></i>
The serialized output of <i>S</i> contains the integer.

<div class="p"><!----></div>
The deserializer for <i>myStruct</i> will automatically set the <i>__type</i>
field and void pointer to the deserialized data, provided that the XML content
for <i>p</i> carries the <tt>xsi:type</tt> attribute from which gSOAP can determine
the type.

<div class="p"><!----></div>
<font color="#FF0000"><b>Important</b></font>: when (de)serializing strings via a <i><b>void</b>*</i> field, the <i><b>void</b>*</i> pointer MUST directly point to the string value rather than indirectly as with all other types. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;myStruct S; <br />
S.p = (<b>void</b>*)"Hello"; <br />
S.__type = SOAP_TYPE_string; <br />
</td></tr></table><br></i>
This is the case for all string-based types, including types defined with <i><b>typedef</b>&nbsp;<b>char</b>*</i>.

<div class="p"><!----></div>
You may use an arbitrary suffix with the <i>__type</i> fields to handle
multiple void pointers in structs/classes.  For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;myStruct <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__typeOfp; // the SOAP_TYPE pointed to by p <br />
&nbsp;&nbsp;&nbsp;<b>void</b>&nbsp;*p; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__typeOfq; // the SOAP_TYPE pointed to by q <br />
&nbsp;&nbsp;&nbsp;<b>void</b>&nbsp;*q; <br />
};
</td></tr></table><br></i>
Because service method parameters are stored within structs, you can use
<i>__type</i> and <i><b>void</b>*</i> parameters to pass polymorphic arguments without
having to define a C++ class hierarchy (Section&nbsp;<a href="#sec:polymorph">11.6.6</a>).  For
example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string; <br />
<b>typedef</b>&nbsp;<b>int</b>&nbsp;xsd__int; <br />
<b>typedef</b>&nbsp;<b>float</b>&nbsp;xsd__float; <br />
<b>enum</b>&nbsp;ns__status { on, off }; <br />
<b>struct</b>&nbsp;ns__widget { xsd__string name; xsd__int part; };
<b>int</b>&nbsp;ns__myMethod(<b>int</b>&nbsp;__type, <b>void</b>&nbsp;*data, <b>struct</b>&nbsp;ns__myMethodResponse { <b>int</b>&nbsp;__type; <b>void</b>&nbsp;*return_; } *out);
</td></tr></table><br></i>
This method has a polymorphic input parameter <i>data</i> and a polymorphic
output parameter <i>return_</i>.  The <i>__type</i> parameters can be one of
<i>SOAP_TYPE_xsd__string</i>, <i>SOAP_TYPE_xsd__int</i>,
<i>SOAP_TYPE_xsd__float</i>, <i>SOAP_TYPE_ns__status</i>, or
<i>SOAP_TYPE_ns__widget</i>.  The WSDL produced by the gSOAP <i>soapcpp2</i> compiler
declares the polymorphic parameters of type <tt>xsd:anyType</tt> which is "too
loose" and doesn't allow the gSOAP importer to handle the WSDL accurately.
Future gSOAP releases might replace <tt>xsd:anyType</tt> with a <tt>choice</tt>
schema type that limits the choice of types to the types declared in the
header file.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.10">
11.10</a>&nbsp;&nbsp;<font color="#0000FF">Fixed-Size Arrays</font></h3>

<div class="p"><!----></div>
Fixed size arrays are encoded as per SOAP 1.1 one-dimensional array types.
Multi-dimensional fixed size arrays are encoded by gSOAP as nested
one-dimensional arrays in SOAP.  Encoding of fixed size arrays supports
partially transmitted and sparse array SOAP formats.

<div class="p"><!----></div>
The decoding of (multi-dimensional) fixed-size arrays supports the SOAP multi-dimensional array format as well as partially transmitted and sparse array formats.

<div class="p"><!----></div>
An example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of header file "fixed.h": <br />
<b>struct</b>&nbsp;Example <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>float</b>&nbsp;a[2][3]; <br />
};
</td></tr></table><br></i>
This specifies a fixed-size array part of the <i><b>struct</b>&nbsp;Example</i>. The encoding of array <i>a</i> is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;a xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="float[][2]"&#62; <br />
&lt;SOAP-ENC:Array xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="float[3]" <br />
&lt;float xsi:type="float"&#62;...&lt;/float&#62; <br />
&lt;float xsi:type="float"&#62;...&lt;/float&#62; <br />
&lt;float xsi:type="float"&#62;...&lt;/float&#62; <br />
&lt;/SOAP-ENC:Array&#62; <br />
&lt;SOAP-ENC:Array xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="float[3]" <br />
&lt;float xsi:type="float"&#62;...&lt;/float&#62; <br />
&lt;float xsi:type="float"&#62;...&lt;/float&#62; <br />
&lt;float xsi:type="float"&#62;...&lt;/float&#62; <br />
&lt;/SOAP-ENC:Array&#62; <br />
&lt;/a&#62;
</td></tr></table><br></tt>
<font color="#FF0000"><b>Caution</b></font>: Any decoded parts of a (multi-dimensional) array that do not "fit" in the fixed size array are ignored by the deserializer.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.11">
11.11</a>&nbsp;&nbsp;<font color="#0000FF">Dynamic Arrays</font></h3><a name="sec:dynarray">
</a>

<div class="p"><!----></div>
As the name suggests, dynamic arrays are much more flexible than fixed-size
arrays and dynamic arrays are better adaptable to the SOAP encoding and decoding
rules for arrays.  In addition, a typical C application allocates a dynamic
array using <i>malloc</i>, assigns the location to a pointer variable, and
deallocates the array later with <i>free</i>.  A typical C++ application
allocates a dynamic array using <i>new</i>, assigns the location to a pointer
variable, and deallocates the array later with <i>delete</i>.  Such dynamic
allocations are flexible, but pose a problem for the serialization of data: how
does the array serializer know the length of the array to be serialized given
only a pointer to the sequence of elements?  The application stores the size
information somewhere. This information is crucial for the array serializer and
has to be made explicitly known to the array serializer by packaging the
pointer and array size information within a <i><b>struct</b></i> or <i><b>class</b></i>.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.11.1">
11.11.1</a>&nbsp;&nbsp;<font color="#0000FF">SOAP Array Bounds Limits</font></h4>

<div class="p"><!----></div>
SOAP encoded arrays use the <tt>SOAP-ENC:Array</tt> type and the <tt>SOAP-ENC:arrayType</tt> attribute to define the array dimensionality and size. As a security measure to avoid denial of service attacks based on sending a huge array size value requiring the allocation of large chunks of memory, the total number of array elements set by the <tt>SOAP-ENC:arrayType</tt> attribute cannot exceed <i>SOAP_MAXARRAYSIZE</i>, which is set to 100,000 by default. This constant is defined in <i>stdsoap2.h</i>. This constant <b>only</b> affects multi-dimensional arrays and the dimensionality of the receiving array will be lost when the number of elements exceeds 100,000. One-dimensional arrays will be populated in sequential order as expected.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.11.2">
11.11.2</a>&nbsp;&nbsp;<font color="#0000FF">One-Dimensional Dynamic SOAP Arrays</font></h4>

<div class="p"><!----></div>
A special form of <i><b>struct</b></i> or <i><b>class</b></i> is used to define one-dimensional
dynamic SOAP-encoded arrays. Each array has a pointer variable and a field that records the
number of elements the pointer points to in memory.

<div class="p"><!----></div>
The general form of the <i><b>struct</b></i> declaration that contains a one-dimensional dynamic SOAP-encoded array is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;some_name <br />
{ <br />
&nbsp;&nbsp;&nbsp;<u><span class="roman">Type</span></u> *__ptr; // pointer to array of elements in memory<br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; // number of elements pointed to <br />
&nbsp;&nbsp;&nbsp;<font size="+1"><span class="roman">[</span></font><font size="+1"><span class="roman">[</span></font><b>static</b>&nbsp;<b>const</b><font size="+1"><span class="roman">]</span></font> <b>int</b>&nbsp;__offset <font size="+1"><span class="roman">[</span></font>= ...<font size="+1"><span class="roman">]</span></font>;<font size="+1"><span class="roman">]</span></font> // optional SOAP 1.1 array offset <br />
&nbsp;&nbsp;&nbsp;... // anything that follows here will be ignored <br />
};
</td></tr></table><br></i>
where <i><u><span class="roman">Type</span></u></i> MUST be a type associated with an XML Schema or MUST be a primitive type.
If these conditions are not met, a vector-like XML (de)serialization is used (see Section&nbsp;<a href="#sec:list">11.11.7</a>).
A primitive type can be used with or without a <i><b>typedef</b></i>.
If the array elements are structs or classes, then the <i>struct</i>/<i>class</i> type names should have a namespace prefix for schema
association, or they should be other (nested) dynamic arrays. 

<div class="p"><!----></div>
An alternative to a <i><b>struct</b></i> is to use a <i><b>class</b></i> with optional methods that MUST appear after the <i>__ptr</i> and
<i>__size</i> fields:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;some_name <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<u><span class="roman">Type</span></u> *__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
&nbsp;&nbsp;&nbsp;<font size="+1"><span class="roman">[</span></font><font size="+1"><span class="roman">[</span></font><b>static</b>&nbsp;<b>const</b><font size="+1"><span class="roman">]</span></font> <b>int</b>&nbsp;__offset <font size="+1"><span class="roman">[</span></font>= ...<font size="+1"><span class="roman">]</span></font>;<font size="+1"><span class="roman">]</span></font> <br />
&nbsp;&nbsp;&nbsp;method1; <br />
&nbsp;&nbsp;&nbsp;method2; <br />
&nbsp;&nbsp;&nbsp;... // any fields that follow will be ignored <br />
};
</td></tr></table><br></i>
To encode the data type as an array, the name of the <i><b>struct</b></i> or
<i><b>class</b></i> SHOULD NOT have a namespace prefix, otherwise the data type will
be encoded and decoded as a generic vector, see Section&nbsp;<a href="#sec:list">11.11.7</a>.

<div class="p"><!----></div>
The deserializer of a dynamic array can decode partially transmitted and/or
SOAP sparse arrays, and even multi-dimensional arrays which will be collapsed
into a one-dimensional array with row-major ordering.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: SOAP 1.2 does not support partially transmitted arrays. So the <i>__offset</i> field of a dynamic array is ignored.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.11.3">
11.11.3</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4>

<div class="p"><!----></div>
The following example header file specifies the XMethods Service Listing service <i>getAllSOAPServices</i> service operation and an array of <i>SOAPService</i> data structures:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "listing.h": <br />
<b>class</b>&nbsp;ns3__SOAPService <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;ID; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*owner; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*description; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*homepageURL; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*endpoint; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*SOAPAction; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*methodNamespaceURI; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*serviceStatus; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*methodName; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*dateCreated; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*downloadURL; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*wsdlURL; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*instructions; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*contactEmail; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*serverImplementation; <br />
}; <br />
<b>class</b>&nbsp;ServiceArray <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;ns3__SOAPService *__ptr; // points to array elements <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; // number of elements pointed to <br />
&nbsp;&nbsp;&nbsp;ServiceArray(); <br />
&nbsp;&nbsp;&nbsp;~ServiceArray(); <br />
&nbsp;&nbsp;&nbsp;<b>void</b>&nbsp;print(); <br />
}; <br />
<b>int</b>&nbsp;ns__getAllSOAPServices(ServiceArray &amp;return_);
</td></tr></table><br></i>
An example client application:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h"
... <br />
// ServiceArray class method implementations: <br />
ServiceArray::ServiceArray() <br />
{ <br />
&nbsp;&nbsp;&nbsp;__ptr = NULL; <br />
&nbsp;&nbsp;&nbsp;__size = 0; <br />
} <br />
ServiceArray::~ServiceArray() <br />
{ // destruction handled by gSOAP <br />
} <br />
<b>void</b>&nbsp;ServiceArray::print() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(<b>int</b>&nbsp;i = 0; i &lt; __size; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cout  &lt;&lt;  __ptr[i].name  &lt;&lt;  ": "  &lt;&lt;  __ptr[i].homepage  &lt;&lt;  endl; <br />
} <br />
... <br />
// Request a service listing and display results: <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;ServiceArray result; <br />
&nbsp;&nbsp;&nbsp;<b>const</b>&nbsp;<b>char</b>&nbsp;*endpoint = "www.xmethods.net:80/soap/servlet/rpcrouter"; <br />
&nbsp;&nbsp;&nbsp;<b>const</b>&nbsp;<b>char</b>&nbsp;*action = "urn:xmethodsServicesManager#getAllSOAPServices"; <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__getAllSOAPServices(&amp;soap, endpoint, action, result); <br />
&nbsp;&nbsp;&nbsp;result.print(); <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;soap_destroy(&amp;soap); // dealloc class instances <br />
&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); // dealloc deserialized data <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); // cleanup and detach soap struct <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.11.4">
11.11.4</a>&nbsp;&nbsp;<font color="#0000FF">One-Dimensional Dynamic SOAP Arrays With Non-Zero Offset</font></h4>

<div class="p"><!----></div>
The declaration of a dynamic array as described in&nbsp;<a href="#sec:dynarray">11.11</a> MAY
include an <i><b>int</b>&nbsp;__offset</i> field. When set to an integer value, the
serializer of the dynamic array will use this field as the start index of the
array and the SOAP array offset attribute will be used in the SOAP payload.
Note that array offsets is a SOAP 1.1 specific feature which is not supported
in SOAP 1.2.

<div class="p"><!----></div>
For example, the following header file declares a mathematical <i>Vector</i>
class, which is a dynamic array of floating point values with an index that
starts at 1:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "vector.h": <br />
<b>typedef</b>&nbsp;<b>float</b>&nbsp;xsd__float; <br />
<b>class</b>&nbsp;Vector <br />
{ <br />
&nbsp;&nbsp;&nbsp;xsd__float *__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__offset; <br />
&nbsp;&nbsp;&nbsp;Vector(); <br />
&nbsp;&nbsp;&nbsp;Vector(<b>int</b>&nbsp;n); <br />
&nbsp;&nbsp;&nbsp;<b>float</b>&amp; <b>operator</b>[](<b>int</b>&nbsp;i); <br />
}
</td></tr></table><br></i>
The implementations of the <i>Vector</i> methods are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
Vector::Vector() <br />
{ <br />
&nbsp;&nbsp;&nbsp;__ptr = NULL; <br />
&nbsp;&nbsp;&nbsp;__size = 0; <br />
&nbsp;&nbsp;&nbsp;__offset = 1; <br />
} <br />
Vector::Vector(<b>int</b>&nbsp;n) <br />
{ <br />
&nbsp;&nbsp;&nbsp;__ptr = (<b>float</b>*)malloc(n*<b>sizeof</b>(<b>float</b>)); <br />
&nbsp;&nbsp;&nbsp;__size = n; <br />
&nbsp;&nbsp;&nbsp;__offset = 1; <br />
} <br />
Vector::~Vector() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(__ptr) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;free(__ptr); <br />
} <br />
<b>float</b>&amp; Vector::<b>operator</b>[](<b>int</b>&nbsp;i) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;__ptr[i-__offset]; <br />
}
</td></tr></table><br></i>
An example program fragment that serializes a vector of 3 elements:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
Vector v(3); <br />
v[1] = 1.0; <br />
v[2] = 2.0; <br />
v[3] = 3.0; <br />
soap_begin(&amp;soap); <br />
v.serialize(&amp;soap); <br />
v.put(<tt>"vec"</tt>); <br />
soap_end(&amp;soap);
</td></tr></table><br></i>
The output is a partially transmitted array:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;vec xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:float[4]" SOAP-ENC:offset="[1]"&#62; <br />
&lt;item xsi:type="xsd:float"&#62;1.0&lt;/item&#62; <br />
&lt;item xsi:type="xsd:float"&#62;2.0&lt;/item&#62; <br />
&lt;item xsi:type="xsd:float"&#62;3.0&lt;/item&#62; <br />
&lt;/vec&#62;
</td></tr></table><br></tt>
Note that the size of the encoded array is necessarily set to 4 and that the encoding omits the non-existent element at index 0.

<div class="p"><!----></div>
The decoding of a dynamic array with an <i>__offset</i> field is more efficient than decoding a dynamic array without an <i>__offset</i> field, because the <i>__offset</i> field will be assigned the value of the <tt>SOAP-ENC:offset</tt> attribute instead of padding the initial part of the array with default values.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.11.5">
11.11.5</a>&nbsp;&nbsp;<font color="#0000FF">Nested One-Dimensional Dynamic SOAP Arrays</font></h4><a name="sec:nested">
</a>

<div class="p"><!----></div>
One-dimensional dynamic arrays MAY be nested.
For example, using <i><b>class</b>&nbsp;Vector</i> declared in the previous section, <i><b>class</b>&nbsp;Matrix</i> is declared:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// Contents of file "matrix.h": <br />
<b>class</b>&nbsp;Matrix <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;Vector *__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__offset; <br />
&nbsp;&nbsp;&nbsp;Matrix(); <br />
&nbsp;&nbsp;&nbsp;Matrix(<b>int</b>&nbsp;n, <b>int</b>&nbsp;m); <br />
&nbsp;&nbsp;&nbsp;~Matrix(); <br />
&nbsp;&nbsp;&nbsp;Vector&amp; <b>operator</b>[](<b>int</b>&nbsp;i); <br />
}; 
</td></tr></table><br></i>
The Matrix type is essentially an array of pointers to arrays which make up the rows of a matrix.
The encoding of the two-dimensional dynamic array in SOAP will be in nested form.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.11.6">
11.11.6</a>&nbsp;&nbsp;<font color="#0000FF">Multi-Dimensional Dynamic SOAP Arrays</font></h4>

<div class="p"><!----></div>
The general form of the <i><b>struct</b></i> declaration for K-dimensional (K &gt; 1) dynamic arrays is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;some_name <br />
{ <br />
&nbsp;&nbsp;&nbsp;<u><span class="roman">Type</span></u> *__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size[K]; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__offset[K]; <br />
&nbsp;&nbsp;&nbsp;... // anything that follows here will be ignored <br />
};
</td></tr></table><br></i>
where <i><u><span class="roman">Type</span></u></i> MUST be a type associated with an XML Schema, which means that it must be a <i><b>typedef</b></i>ed type
in case of a primitive type, or a <i><b>struct</b></i>/<i><b>class</b></i> name with a namespace prefix for schema association, or another dynamic array. If these conditions are not met, a generic vector XML (de)serialization is used (see Section&nbsp;<a href="#sec:list">11.11.7</a>).

<div class="p"><!----></div>
An alternative is to use a <i><b>class</b></i> with optional methods:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;some_name <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<u><span class="roman">Type</span></u> *__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size[K]; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__offset[K]; <br />
&nbsp;&nbsp;&nbsp;method1; <br />
&nbsp;&nbsp;&nbsp;method2; <br />
&nbsp;&nbsp;&nbsp;... // any fields that follow will be ignored <br />
};
</td></tr></table><br></i>
In the above, K is a constant denoting the number of dimensions of the multi-dimensional array.

<div class="p"><!----></div>
To encode the data type as an array, the name of the <i><b>struct</b></i> or <i><b>class</b></i> SHOULD NOT have a namespace prefix, otherwise
the data type will be encoded and decoded as a generic vector, see Section&nbsp;<a href="#sec:list">11.11.7</a>.

<div class="p"><!----></div>
The deserializer of a dynamic array can decode partially transmitted multi-dimensional arrays.

<div class="p"><!----></div>
For example, the following declaration specifies a matrix class:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>double</b>&nbsp;xsd__double; <br />
<b>class</b>&nbsp;Matrix <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;xsd__double *__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size[2]; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__offset[2]; <br />
}; 
</td></tr></table><br></i>
In contrast to the matrix class of Section&nbsp;<a href="#sec:nested">11.11.5</a> that defined a matrix as an array of pointers to matrix rows, this
class has one pointer to a matrix stored in row-major order.  The size of the matrix is determined by the <i>__size</i> field:
<i>__size[0]</i> holds the number of rows and <i>__size[1]</i> holds the number of columns of the matrix.  Likewise, <i>__
offset[0]</i> is the row offset and <i>__offset[1]</i> is the columns offset.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.11.7">
11.11.7</a>&nbsp;&nbsp;<font color="#0000FF">Encoding XML Generics Containing Dynamic Arrays</font></h4><a name="sec:list">
</a>

<div class="p"><!----></div>
The XML "generics" concept discussed in the SOAP encoding protocols extends the concept of a SOAP struct by allowing repetitions of elements within the struct. This is just a form of a repetition of XML elements without the SOAP-encoded array requirements. While SOAP-encoded arrays are more expressive (offset information to encode sparse arrays for example), simple repetitions of values are used more frequently.

<div class="p"><!----></div>
A simple generic reperition is an array-like data structure with a repetition of an element.
To achieve this, declare a dynamic array as a <i><b>struct</b></i> or <i><b>class</b></i> with a name that is qualified with
a namespace prefix.  SOAP arrays are declared without prefix.

<div class="p"><!----></div>
For example, we define a Map structure that contains a sequence of pairs of key-val:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__Map <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; // number of pairs <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;ns__Binding {<b>char</b>&nbsp;*key; <b>char</b>&nbsp;*val;} *pair; <br />
};
</td></tr></table><br></i>
Since 2.7.16 it is also possible to use a '<i>$</i>' as a special marker to annotate a
size field that must be of type <i><b>int</b></i> or <i>size_t</i> and the field
name is no longer relevant:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__Map <br />
{ <br />
&nbsp;&nbsp;&nbsp;$<b>int</b>&nbsp;length; // number of pairs <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;ns__Binding {<b>char</b>&nbsp;*key; <b>char</b>&nbsp;*val;} *pair; <br />
};
</td></tr></table><br></i>
This declares a dynamic array pointed to by <i>pair</i> and size <i>__size</i>. The array will be serialized and deserialized as a sequence of pairs:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;ns:Map xsi:type="ns:Map"&#62; <br />
&lt;pair xsi:type="ns:Binding"&#62; <br />
&lt;key&#62;Joe&lt;/key&#62; <br />
&lt;val&#62;555 77 1234&lt;/val&#62; <br />
&lt;/pair&#62; <br />
&lt;pair xsi:type="ns:Binding"&#62; <br />
&lt;key&#62;Susan&lt;/key&#62; <br />
&lt;val&#62;555 12 6725&lt;/val&#62; <br />
&lt;/pair&#62; <br />
&lt;pair xsi:type="ns:Binding"&#62; <br />
&lt;key&#62;Pete&lt;/key&#62; <br />
&lt;val&#62;555 99 4321&lt;/val&#62; <br />
&lt;/pair&#62; <br />
&lt;/ns:Map&#62;
</td></tr></table><br></tt>
Deserialization is less efficient compared to a SOAP-encoded array, because the size of the
sequence is not part of the SOAP encoding. Internal buffering is used by the
deserializer to collect the elements. When the end of the list is reached, the
buffered elements are copied to a newly allocated space on the heap for the
dynamic array.

<div class="p"><!----></div>
Multiple arrays can be used in a struct/class to support the concept of
"generics".  Each array results in a repetition of elements in the struct/class.
This is achieved with a <i><b>int</b>&nbsp;__size</i> (or <i>$<b>int</b></i>) field in
the struct/class where the next field (i.e.&nbsp;below the <i>__size</i> field) is a
pointer type.  The pointer
type is assumed to point to an array of values at run time.  The <i>__size</i>
field holds the number of values at run time.  Multiple arrays can be embedded
in a struct/class with <i>__size</i> fields that have a distinct names.  To
make the <i>__size</i> fields distinct, you can end them with a unique name
suffix such as <i>__sizeOfstrings</i>, for example.

<div class="p"><!----></div>
The general convention for embedding arrays is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__SomeStruct <br />
{ <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size<u><span class="roman">name1</span></u>; // number of elements pointed to <br />
&nbsp;&nbsp;&nbsp;<u><span class="roman">Type1</span></u> *<u>field1</u>; // by this field <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size<u><span class="roman">name2</span></u>; // number of elements pointed to <br />
&nbsp;&nbsp;&nbsp;<u><span class="roman">Type2</span></u> *<u>field2</u>; // by this field <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
where <i><u><span class="roman">name1</span></u></i> and <i><u><span class="roman">name2</span></u></i> are identifiers used as a suffix to distinguish the <i>__size</i> field. These names can be arbitrary and are not visible in XML.

<div class="p"><!----></div>
In 2.7.16 and higher this is simplified with a '<i>$</i>' marker:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__SomeStruct <br />
{ <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;$<b>int</b>&nbsp;<u><span class="roman">name1</span></u>; // number of elements pointed to <br />
&nbsp;&nbsp;&nbsp;<u><span class="roman">Type1</span></u> *<u>field1</u>; // by this field <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;$<b>int</b>&nbsp;<u><span class="roman">name2</span></u>; // number of elements pointed to <br />
&nbsp;&nbsp;&nbsp;<u><span class="roman">Type2</span></u> *<u>field2</u>; // by this field <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
For example, the following struct has two embedded arrays:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__Contact <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*firstName; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*lastName; <br />
&nbsp;&nbsp;&nbsp;$<b>int</b>nPhones; // number of Phones<br />
&nbsp;&nbsp;&nbsp;ULONG64 *phoneNumber; // array of phone numbers <br />
&nbsp;&nbsp;&nbsp;$<b>int</b>nEmails; // number of emails <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;**emailAddress; // array of email addresses <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*socSecNumber; <br />
};
</td></tr></table><br></i>
The XML serialization of an example <i>ns__Contact</i> is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;mycontact xsi:type="ns:Contact"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;firstName&#62;Joe&lt;/firstName&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;lastName&#62;Smith&lt;/lastName&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;phoneNumber&#62;5551112222&lt;/phoneNumber&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;phoneNumber&#62;5551234567&lt;/phoneNumber&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;phoneNumber&#62;5552348901&lt;/phoneNumber&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;emailAddress&#62;Joe.Smith@mail.com&lt;/emailAddress&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;emailAddress&#62;Joe@Smith.com&lt;/emailAddress&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;socSecNumber&#62;999999999&lt;/socSecNumber&#62; <br />
&lt;/mycontact&#62;
</td></tr></table><br></tt>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.11.8">
11.11.8</a>&nbsp;&nbsp;<font color="#0000FF">STL Containers</font></h4><a name="sec:templates">
</a>

<div class="p"><!----></div>
gSOAP supports the STL containers <i>std::deque</i>, <i>std::list</i>,
<i>std::set</i>, and <i>std::vector</i>.

<div class="p"><!----></div>
STL containers can only be used within classes to declare members that contain
multiple values.  This is somewhat similar to the embedding of arrays in
structs in C as explained in Section&nbsp;<a href="#sec:list">11.11.7</a>, but the STL container
approach is more flexible.

<div class="p"><!----></div>
You need to import <i>stldeque.h</i>, <i>stllist.h</i>, <i>stlset.h</i>, or
<i>stlvector.h</i> to enable <i>std::deque</i>, <i>std::list</i>, <i>std::set</i>,
and <i>std::vector</i> (de)serialization.
Here is an example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "stlvector.h" <br />
<b>class</b>&nbsp;ns__myClass <br />
{ <b>public</b>: <br />
&nbsp;&nbsp;&nbsp;std::vector &lt; int &gt;  *number; <br />
&nbsp;&nbsp;&nbsp;std::vector &lt; xsd__string &gt;  *name; <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
The use of pointer members is not required but advised. The reason is that
interoperability with other SOAP toolkits may lead to copying of <i>ns__
myClass</i> instances at run time when (de)serializing multi-referenced data.
When a copy is made, certain parts of the containers will be shared between the
copies which could lead to disaster when the classes with their containers are
deallocated.  Another way to avoid this is to declare class <i>ns__myClass</i>
within other data types via a pointer.  (Interoperability between gSOAP clients
and services does not lead to copying.)

<div class="p"><!----></div>
The XML Schema that corresponds to the <i>ns__myClass</i> type is
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;complexType name="myClass"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;sequence&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="number" type="xsd:int" minOccurs="1" maxOccurs="unbounded"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="name" type="xsd:string" minOccurs="1" maxOccurs="unbounded"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;&lt;/sequence&#62; <br />
&lt;/complexType&#62;
</td></tr></table><br></tt>
You can specify the minOccurs and maxOccurs values as explained in Section&nbsp;<a href="#sec:directives">19.2</a>.

<div class="p"><!----></div>
You can also implement your own
containers similar to STL containers. The containers must be class templates and should define an iterator type, and <i><b>void</b>&nbsp;clear()</i>, <i>iterator begin()</i>, <i>iterator end()</i>, and <i>iterator insert(iterator pos, const_reference val)</i>.
The <i>iterator</i> should have a dereference operator to
access the container's elements.  The dereference operator is used by gSOAP to
send a sequence of XML element values.  The <i>insert</i> method can be used as
a setter method.  gSOAP reads a sequence of XML element values and inserts them
in the container via this method.  

<div class="p"><!----></div>
Here is in example user-defined container template class:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
// simpleVector.h <br />
<b>template</b>&nbsp; &lt; <b>class</b>&nbsp;T &gt;  <br />
<b>class</b>&nbsp;simpleVector <br />
{ <br />
<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>typedef</b>&nbsp;T			  value_type; <br />
&nbsp;&nbsp;&nbsp;<b>typedef</b>&nbsp;value_type		* pointer; <br />
&nbsp;&nbsp;&nbsp;<b>typedef</b>&nbsp;const value_type	* const_pointer; <br />
&nbsp;&nbsp;&nbsp;<b>typedef</b>&nbsp;value_type		&amp; reference; <br />
&nbsp;&nbsp;&nbsp;<b>typedef</b>&nbsp;const value_type	&amp; const_reference; <br />
&nbsp;&nbsp;&nbsp;<b>typedef</b>&nbsp;pointer		  iterator; <br />
&nbsp;&nbsp;&nbsp;<b>typedef</b>&nbsp;const_pointer		  const_iterator; <br />
<b>protected</b>: <br />
&nbsp;&nbsp;&nbsp;iterator			  start; <br />
&nbsp;&nbsp;&nbsp;iterator			  finish; <br />
&nbsp;&nbsp;&nbsp;size_t			  length; <br />
<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;simpleVector()	{ clear(); } <br />
&nbsp;&nbsp;&nbsp;~simpleVector()	{ <b>delete</b>[] start; } <br />
&nbsp;&nbsp;&nbsp;<b>void</b>\				  clear()		{ start = finish = NULL; } <br />
&nbsp;&nbsp;&nbsp;iterator			  begin()		{ <b>return</b>&nbsp;start; } <br />
&nbsp;&nbsp;&nbsp;const_iterator		  begin() <b>const</b>\		{ <b>return</b>&nbsp;start; } <br />
&nbsp;&nbsp;&nbsp;iterator			  end()			{ <b>return</b>&nbsp;finish; } <br />
&nbsp;&nbsp;&nbsp;const_iterator		  end() <b>const</b>\		{ <b>return</b>&nbsp;finish; } <br />
&nbsp;&nbsp;&nbsp;size_t		  size() <b>const</b>\		{ <b>return</b>&nbsp;finish-start; } <br />
&nbsp;&nbsp;&nbsp;iterator			  insert(iterator pos, const_reference val) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!start) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;start = finish = <b>new</b>&nbsp;value_type[length = 4]; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<b>if</b>&nbsp;(finish <tt>&gt;=</tt> start + length) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;iterator i = start; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;iterator j = <b>new</b>&nbsp;value_type[2 * length]; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;start = j; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;finish = start + length; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length *= 2; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(pos) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pos = j + (pos - i); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>while</b>&nbsp;(i != finish) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*j++ = *i++; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(pos &amp;&amp; pos != finish) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ iterator i = finish; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;iterator j = i - 1; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>while</b>&nbsp;(j != pos) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*i&#8722;&nbsp;&#8722; = *j&#8722;&nbsp;&#8722;; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*finish++ = val; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;pos; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
};
</td></tr></table><br></i>
To enable the container, we add the following two lines to our gSOAP header file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "simpleVector.h" <br />
<b>template</b>&nbsp; &lt; class T &gt;  <b>class</b>&nbsp;simpleVector;
</td></tr></table><br></i>
The container class
should not be defined in the gSOAP header file. It must be defined in
a separate header file (e.g.&nbsp;"simpleVector.h"). The <i><b>template</b>&nbsp; &lt; class T &gt;  <b>class</b>&nbsp;simpleVector</i> declaration ensures that gSOAP will recognize <i>simpleVector</i> as a container class.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: when parsing XML content the container elements may not be stored in the same order given in
the XML content.  When gSOAP parses XML it uses the <i>insert</i> container methods to
store elements one by one.  However, element content that is "forwarded" with
<tt>href</tt> attributes will be appended to the container.  Forwarding can take
place with multi-referenced data that is referred to from the main part of the
SOAP 1.1 XML message to the independent elements that carry <tt>id</tt>s.
Therefore, your application should not rely on the preservation of the order of
elements in a container.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.11.9">
11.11.9</a>&nbsp;&nbsp;<font color="#0000FF">Polymorphic Dynamic Arrays and Lists</font></h4>

<div class="p"><!----></div>
Polymorphic arrays (arrays of polymorphic element types) can be encoded when
declared as an array of pointers to class instances. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;ns__Object <br />
{<br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;... <br />
}; <br />
<b>class</b>&nbsp;ns__Data: <b>public</b>&nbsp;ns__Object <br />
{<br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;... <br />
}; <br />
<b>class</b>&nbsp;ArrayOfObject <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;ns__Object **__ptr; // pointer to array of pointers to Objects <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; // number of Objects pointed to <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__offset; // optional SOAP 1.1 array offset <br />
}; <br />
<b>class</b>&nbsp;ns__Objects <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;std::vector &lt; ns__Object* &gt;  objects; // vector of pointers to objects <br />
};
</td></tr></table><br></i>
The pointers in the array can point to the <i>ns__Object</i> base class or
<i>ns__Data</i> derived class instances which will be serialized and
deserialized accordingly in SOAP.  That is, the array elements are polymorphic.

<div class="p"><!----></div>
Since we can't use dynamic binding to support polymorphism in C, another
mechanism is available based on the serialization of void pointers, that is, dynamic serialization of data referenced by void pointers, see Section&nbsp;<a href="#sec:void">11.9</a>.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;__wrapper <br />
{<br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__type; // type T represented by SOAP_TYPE_T <br />
&nbsp;&nbsp;&nbsp;<b>void</b>&nbsp;*__item; // pointer to data of type T <br />
}; <br />
<b>struct</b>&nbsp;ArrayOfObject <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;__wrapper __ptr; // pointer to array of pointers to Objects <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; // number of Objects pointed to <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__offset; // optional SOAP 1.1 array offset <br />
}; <br />
<b>struct</b>&nbsp;ns__Objects <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;__wrapper *objects; // array of pointers to wrapped types <br />
};
</td></tr></table><br></i>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc11.11.10">
11.11.10</a>&nbsp;&nbsp;<font color="#0000FF">How to Change the Tag Names of the Elements of a SOAP Array or List</font></h4>

<div class="p"><!----></div>
The <i>__ptr</i> field in a <i><b>struct</b></i> or <i><b>class</b></i> declaration of a dynamic array may have an optional suffix part that
describes the name of the tags of the SOAP array XML elements.
The suffix is part of the field name:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<u><span class="roman">Type</span></u> *__ptr<u><span class="roman">array_elt_name</span></u>
</td></tr></table><br></i>
The suffix describes the tag name to be used for all array elements. The usual identifier to XML translations apply, see
Section&nbsp;<a href="#sec:idtrans">10.3</a>.
The default XML element tag name for array elements is <tt>item</tt> (which corresponds to the use of field name <i>__ptritem</i>).

<div class="p"><!----></div>
Consider for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ArrayOfstring <br />
{ <br />
&nbsp;&nbsp;&nbsp;xsd__string *__ptrstring;
&nbsp;&nbsp;&nbsp;int __size;
};
</td></tr></table><br></i>
The array is serialized as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;array xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:string[2]"&#62; <br />
&lt;string xsi:type="xsd:string"&#62;Hello&lt;/string&#62; <br />
&lt;string xsi:type="xsd:string"&#62;World&lt;/string&#62; <br />
&lt;/array&#62;
</td></tr></table><br></tt>
SOAP 1.1 and 1.2 do not require the use of a specific tag name for array elements.  gSOAP will deserialize a SOAP array while
ignoring the tag names. Certain XML Schemas used in doc/literal encoding may require the declaration of array element tag names.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.12">
11.12</a>&nbsp;&nbsp;<font color="#0000FF">Base64Binary XML Schema Type Encoding</font></h3><a name="sec:base64binary">
</a>

<div class="p"><!----></div>
The <tt>base64Binary</tt> XML Schema type is a special form of dynamic array declared with a pointer (<i>__ptr</i>) to an
<i><b>unsigned</b>&nbsp;<b>char</b></i> array.

<div class="p"><!----></div>
For example using a <i><b>struct</b></i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;xsd__base64Binary <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
};
</td></tr></table><br></i>
Or with a <i><b>class</b></i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;xsd__base64Binary <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
};
</td></tr></table><br></i>
When compiled by the gSOAP <i>soapcpp2</i> tool, this header file specification will generate <tt>base64Binary</tt> serializers and deserializers.

<div class="p"><!----></div>
The <tt>SOAP_ENC:base64</tt> encoding is another type for base 64 binary encoding
specified by the SOAP data type schema and some SOAP applications may use this form
(as indicated by their WSDL descriptions). It is declared by:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;SOAP_ENC__base64 <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
};
</td></tr></table><br></i>
Or with a <i><b>class</b></i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;SOAP_ENC__base64 <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
};
</td></tr></table><br></i>
When compiled by the gSOAP <i>soapcpp2</i> tool, this header file specification will generate <tt>SOAP-ENC:base64</tt> serializers and deserializers.

<div class="p"><!----></div>
The advantage of using a <i><b>class</b></i> is that methods can be used to initialize and manipulate the <i>__ptr</i> and <i>__size</i> fields. The user can add methods to this class to do this. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;xsd__base64Binary <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
&nbsp;&nbsp;&nbsp;xsd__base64Binary(); // Constructor <br />
&nbsp;&nbsp;&nbsp;xsd__base64Binary(<b>struct</b>&nbsp;soap *soap, <b>int</b>&nbsp;n); // Constructor <br />
&nbsp;&nbsp;&nbsp;~xsd__base64Binary(); // Destructor <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*location(); // returns the memory location <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;size(); // returns the number of bytes <br />
};
</td></tr></table><br></i>
Here are example method implementations:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
xsd__base64Binary::xsd__base64Binary() <br />
{ <br />
&nbsp;&nbsp;&nbsp;__ptr = NULL; <br />
&nbsp;&nbsp;&nbsp;__size = 0; <br />
} <br />
xsd__base64Binary::xsd__base64Binary(<b>struct</b>&nbsp;soap *soap, <b>int</b>&nbsp;n) <br />
{ <br />
&nbsp;&nbsp;&nbsp;__ptr = (<b>unsigned</b>&nbsp;<b>char</b>*)soap_malloc(soap, n); <br />
&nbsp;&nbsp;&nbsp;__size = n; <br />
} <br />
xsd__base64Binary::~xsd__base64Binary() <br />
{ } <br />
<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*xsd__base64Binary::location() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;__ptr; <br />
} <br />
<b>int</b>&nbsp;xsd__base64Binary::size() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;__size; <br />
}
</td></tr></table><br></i>
The following example in C/C++ reads from a raw image file and encodes the image in SOAP using the <tt>base64Binary</tt> type:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
... <br />
FILE *fd = fopen(<tt>"image.jpg"</tt>, <tt>"rb"</tt>); <br />
xsd__base64Binary image(&amp;soap, filesize(fd)); <br />
fread(image.location(), image.size(), 1, fd); <br />
fclose(fd); <br />
soap_begin(&amp;soap); <br />
image.soap_serialize(&amp;soap); <br />
image.soap_put(&amp;soap, <tt>"jpegimage"</tt>, NULL); <br />
soap_end(&amp;soap); <br />
...
</td></tr></table><br></i>
where <i>filesize</i> is a function that returns the size of a file given a file descriptor.

<div class="p"><!----></div>
Reading the <tt>xsd:base64Binary</tt> encoded image.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
... <br />
xsd__base64Binary image; <br />
soap_begin(&amp;soap); <br />
image.get(&amp;soap, <tt>"jpegimage"</tt>); <br />
soap_end(&amp;soap); <br />
...
</td></tr></table><br></i>
The <i><b>struct</b></i> or <i><b>class</b></i> name <i>soap_enc__base64</i> should be used for <tt>SOAP-ENC:base64</tt> schema type instead of
<i>xsd__base64Binary</i>.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.13">
11.13</a>&nbsp;&nbsp;<font color="#0000FF">hexBinary XML Schema Type Encoding</font></h3><a name="sec:hexbinary">
</a>

<div class="p"><!----></div>
The <tt>hexBinary</tt> XML Schema type is a special form of dynamic array declared with the name <i>xsd__hexBinary</i> and a pointer (<i>__ptr</i>) to an <i><b>unsigned</b>&nbsp;<b>char</b></i> array.

<div class="p"><!----></div>
For example, using a <i><b>struct</b></i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;xsd__hexBinary <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
};
</td></tr></table><br></i>
Or using a <i><b>class</b></i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;xsd__hexBinary <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>public</b>: <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
};
</td></tr></table><br></i>
When compiled by the gSOAP <i>soapcpp2</i> tool, this header file specification will generate <tt>base64Binary</tt> serializers and deserializers.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc11.14">
11.14</a>&nbsp;&nbsp;<font color="#0000FF">Literal XML Encoding Style</font></h3><a name="sec:literal">
</a>

<div class="p"><!----></div>
gSOAP supports document/literal encoding by default.
Just as with SOAP RPC encoding, literal encoding requires the XML Schema of the message data to be provided
e.g.&nbsp;in WSDL in order for the
gSOAP <i>soapcpp2</i> compiler to generate the (de)serialization routines.  Alternatively, the
optional DOM parser (<i>dom.c</i> and <i>dom++.cpp</i>) can be used to handle generic XML or
arbitrary XML documents can be (de)serialized into regular C strings or wide
character strings (<i>wchar_t*</i>) by gSOAP (see Section&nbsp;<a href="#sec:literal2">11.14.1</a>).

<div class="p"><!----></div>
The <i>//gsoap service encoding</i>, <i>//gsoap service method-encoding</i>, and <i>//gsoap service method-response-encoding</i> directives explicitly enable SOAP encoded or literal encoded messages. For example, to enable RPC encoding style for the entire service, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service encoding: encoded
</td></tr></table><br></i>
To enable encoding for particular service methods, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service method-encoding: myMethod encoded <br />
<b>int</b>&nbsp;ns__myMethod(...)
</td></tr></table><br></i>
To enable encoding for particular service methods responses when the method request is literal, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service method-response-encoding: myMethod encoded <br />
<b>int</b>&nbsp;ns__myMethod(...)
</td></tr></table><br></i>
Instead of the <i>encoded</i> value, you can use <i>literal</i>, or a specific encoding style value.

<div class="p"><!----></div>
Consider the following example that uses the directive to make the literal encoding explicit.
The <i>LocalTimeByZipCode</i> service operation of the LocalTime service provides
the local time given a zip code and uses literal encoding (with MS
.NET).  The following header file declares the method: <br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>int
LocalTimeByZipCode(<b>char</b>&nbsp;*ZipCode, <b>char</b>&nbsp;**LocalTimeByZipCodeResult);
</td></tr></table><br></i> Note that none of the data types need to be namespace qualified using
namespace prefixes.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service name: localtime <br />
//gsoap ns service encoding: literal <br />
//gsoap ns service namespace: http://alethea.net/webservices/ <br />
<b>int</b>&nbsp;ns__LocalTimeByZipCode(<b>char</b>&nbsp;*ZipCode, <b>char</b>&nbsp;**LocalTimeByZipCodeResult);
</td></tr></table><br></i>
In this case, the method name requires to be associated with a schema through a namespace prefix, e.g. <i>ns</i> is used in this example.
See Section&nbsp;<a href="#sec:directives">19.2</a> for more details on gSOAP directives.
With these directives, the gSOAP <i>soapcpp2</i> compiler generates client and server sources with the specified settings.

<div class="p"><!----></div>
The example client program is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
#include "localtime.nsmap" // include generated map file <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*t; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_ns__LocalTimeByZipCode(&amp;soap, "http://alethea.net/webservices/LocalTime.asmx", "http://alethea.net/webservices/LocalTimeByZipCode", "32306", &amp;t)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf("Time = %s<tt>\n</tt>", t); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
} <br />
</td></tr></table><br></i>

<div class="p"><!----></div>
To illustrate the manual doc/literal setting, the following client program sets
the required properties before the call:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
#include "localtime.nsmap" // include generated map file <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*t; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap.encodingStyle = NULL; // don't use SOAP encoding <br />
&nbsp;&nbsp;&nbsp;soap_set_omode(&amp;soap, SOAP_XML_TREE);" // don't produce multi-ref data (but can accept) <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_ns__LocalTimeByZipCode(&amp;soap, "http://alethea.net/webservices/LocalTime.asmx", "http://alethea.net/webservices/LocalTimeByZipCode", "32306", &amp;t)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf("Time = %s<tt>\n</tt>", t); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
}
</td></tr></table><br></i>
The SOAP request is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
POST /webservices/LocalTime.asmx HTTP/1.0 <br />
Host: alethea.net <br />
Content-Type: text/xml; charset=utf-8 <br />
Content-Length: 479 <br />
SOAPAction: "http://alethea.net/webservices/LocalTimeByZipCode" <br />
<br />
&lt;?xml version="1.0" encoding="UTF-8"?&#62; <br />
&lt;SOAP-ENV:Envelope <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsd="http://www.w3.org/2001/XMLSchema" <br />
&nbsp;&nbsp;&nbsp;&lt;SOAP-ENV:Body&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;LocalTimeByZipCode xmlns="http://alethea.net/webservices/"&#62; <br />
&lt;ZipCode&#62;32306&lt;/ZipCode&#62;&lt;/LocalTimeByZipCode&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/SOAP-ENV:Body&#62; <br />
&lt;/SOAP-ENV:Envelope&#62;
</td></tr></table><br></tt>

<div class="p"><!----></div>
	      <h4><a name="tth_sEc11.14.1">
11.14.1</a>&nbsp;&nbsp;<font color="#0000FF">Serializing and Deserializing Mixed Content XML With Strings</font></h4><a name="sec:literal2">
</a>

<div class="p"><!----></div>
To declare a literal XML "type" to hold XML documents in regular strings, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*XML;
</td></tr></table><br></i>
To declare a literal XML "type" to hold XML documents in wide character strings, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;wchar_t *XML;
</td></tr></table><br></i>
Note: only one of the two storage formats can be used.
The differences between the use of regular strings versus wide character strings for XML documents are:

<ul>
<li> Regular strings for XML documents MUST hold UTF-8 encoded XML documents. That is, the string MUST contain the proper UTF-8
encoding to exchange the XML document in SOAP messages.
<div class="p"><!----></div>
</li>

<li> Wide character strings for XML documents SHOULD NOT hold UTF-8 encoded XML documents. Instead, the UTF-8 translation is done automatically by
the gSOAP runtime marshalling routines.
<div class="p"><!----></div>
</li>
</ul>
Here is a C++ example of a service operation specification in which the parameters of the service operation uses literal XML encoding to pass
an XML document to a service and back:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*XML; <br />
ns__GetDocument(XML m__XMLDoc, XML &amp;m__XMLDoc_);
</td></tr></table><br></i>
and in C:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*XML; <br />
ns__GetDocument(XML m__XMLDoc, XML *m__XMLDoc_);
</td></tr></table><br></i>
The <i>ns__Document</i> is essentially a <i><b>struct</b></i> that forms the root of the XML document.
The use of the underscore in the <i>ns__Document</i> response part of the message avoids the name clash between the
<i><b>struct</b></i>s.
Assuming that the namespace mapping table contains the binding of <i>ns</i> to <tt>http://my.org/</tt>
and the binding of <i>m</i> to <tt>http://my.org/mydoc.xsd</tt>, the XML message is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;?xml version="1.0" encoding="UTF-8"?&#62; <br />
&lt;SOAP-ENV:Envelope <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" <br />
&nbsp;&nbsp;&nbsp;xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <br />
&nbsp;&nbsp;&nbsp;xmlns:xsd="http://www.w3.org/2001/XMLSchema" <br />
&nbsp;&nbsp;&nbsp;xmlns:ns="http://my.org/" <br />
&nbsp;&nbsp;&nbsp;xmlns:m="http://my.org/mydoc.xsd" <br />
&nbsp;&nbsp;&nbsp;SOAP-ENV:encodingStyle=""&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;SOAP-ENV:Body&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;ns:GetDocument&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;XMLDoc xmlns="http://my.org/mydoc.xsd"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/XMLDoc&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/ns:Document&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/SOAP-ENV:Body&#62; <br />
&lt;/SOAP-ENV:Envelope&#62;
</td></tr></table><br></tt>
When using literal encoding of method parameters and response as shown in the example above, the literal XML encoding style MUST be specified by setting <i>soap.encodingStyle</i>.
For example, to specify no constraints on the encoding style (which is typical) use NULL:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
soap.encodingStyle = NULL;
</td></tr></table><br></i>
As a result, the <tt>SOAP-ENV:encodingStyle</tt> attribute will not appear in the SOAP payload.

<div class="p"><!----></div>
For interoperability with Apache SOAP, use
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
soap.encodingStyle = "http://xml.apache.org/xml-soap/literalxml";
</td></tr></table><br></i>
When the response parameter is an XML type, it will store the entire XML response content but without the enveloping response element.

<div class="p"><!----></div>
The XML type can be used as part of any data structure to enable the rendering and parsing of custom XML documents. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*XML; <br />
<b>struct</b>&nbsp;ns__Data /* data in namespace 'ns' */ <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;number; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;XML m__document; /* XML document in default namespace 'm' */ <br />
}; <br />
ns__Example(<b>struct</b>&nbsp;ns__Data data, <b>struct</b>&nbsp;ns__ExampleResponse { <b>struct</b>&nbsp;ns__Data data; } *out);
</td></tr></table><br></i>

<div class="p"><!----></div>
 <h2><a name="tth_sEc12">
12</a>&nbsp;&nbsp;<font color="#0000FF">SOAP Fault Processing</font></h2><a name="sec:fault">
</a>

<div class="p"><!----></div>
A predeclared standard SOAP Fault data structure is generated by the gSOAP <i>soapcpp2</i> tool for exchanging exception messages.
The built-in <i><b>struct</b>&nbsp;SOAP_ENV__Fault</i> data structure is defined as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;SOAP_ENV__Fault <br />
{ <br />
&nbsp;&nbsp;&nbsp;_QName faultcode; // _QName is builtin <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*faultstring; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*faultactor; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;SOAP_ENV__Detail *detail; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;SOAP_ENV__Code *SOAP_ENV__Code; // MUST be a SOAP_ENV__Code struct defined below <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*SOAP_ENV__Reason; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*SOAP_ENV__Node; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*SOAP_ENV__Role; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;SOAP_ENV__Detail *SOAP_ENV__Detail; // SOAP 1.2 detail field <br />
};
<b>struct</b>&nbsp;SOAP_ENV__Code <br />
{ <br />
&nbsp;&nbsp;&nbsp;_QName SOAP_ENV__Value; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;SOAP_ENV__Code *SOAP_ENV__Subcode;
}; <br />
<b>struct</b>&nbsp;SOAP_ENV__Detail <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__type; // The SOAP_TYPE_ of the object serialized as Fault detail <br />
&nbsp;&nbsp;&nbsp;<b>void</b>&nbsp;*fault; // pointer to the fault object, or NULL <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*__any; // any other detail element content (stored in XML format) <br />
};
</td></tr></table><br></i>
The first four fields in <i>SOAP_ENV__Fault</i> are SOAP 1.1 specific. The last five fields are SOAP 1.2 specific.
You can redefine these structures in the header file. For example, you can use a <i>class</i> for the <i>SOAP_ENV__Fault</i> and add methods for convenience.

<div class="p"><!----></div>
The data structure content can be changed to the need of an application, but this is generally not necessary because the application-specific SOAP Fault details can be serialized via the <i>__type</i> and <i>fault</i> fields in the <i>SOAP_ENV__Detail</i> field, see Section&nbsp;<a href="#sec:void">11.9</a> on the serialization of data refered to by <i>__type</i> and <i>fault</i>.

<div class="p"><!----></div>
The <i>__type</i> field allows application data to be serialized as part of the SOAP Fault. The application data SHOULD be defined as XML elements, which requires you to declare the type names with a leading underscore to ensure that the types are compatible with XML elements and not just simpleTypes and complexTypes.

<div class="p"><!----></div>
When the skeleton of a service operation returns an error (see Section&nbsp;<a href="#sec:errcodes">10.2</a>), then <i>soap.fault</i> contains the SOAP
Fault data at the receiving side (client).

<div class="p"><!----></div>
Server-side faults are raised with <i>soap_sender_fault</i> or <i>soap_receiver_fault</i>. The <i>soap_sender_fault</i> call should be used to inform that the sender is at fault and the sender (client) should not resend the request. The <i>soap_receiver_fault</i> call should be used to indicate a temporary server-side problem, so a sender (client) can resend the request later. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns1__myMethod(<b>struct</b>&nbsp;soap *soap, ...) <br />
{ <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_receiver_fault(soap, "Resource temporarily unavailable", NULL); // return fault to sender <br />
}
</td></tr></table><br></i>
In the example, the SOAP Fault details were empty (NULL). You may pass an XML fragment, which will be literally included in the SOAP Fault message. For WS-I Basic Profile compliance, you must pass an XML string with one or more namespace qualified elements, such as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>return</b>&nbsp;soap_receiver_fault(soap, "Resource temporarily unavailable", " &lt; errorcode xmlns='http://tempuri.org' &gt; 123 &lt; /errorcode &gt;  &lt; errorinfo xmlns='http://tempuri.org' &gt; abc &lt; /errorinfo &gt; ");
</td></tr></table><br></i>

<div class="p"><!----></div>
When a service operation must raise an exception with application SOAP Fault details, it does so by assigning the <i>soap.fault</i> field of the current reference to the
runtime context with 
appropriate data associated with the exception and by returning the error <i>SOAP_FAULT</i>.
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
&nbsp;&nbsp;&nbsp;soap_receiver_fault(soap, "Stack dump", NULL); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap<tt>-&gt;</tt>version == 2) // SOAP 1.2 is used <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>fault<tt>-&gt;</tt>SOAP_ENV__Detail = (<b>struct</b>&nbsp;SOAP_ENV__Detail*)soap_malloc(soap, sizeof(<b>struct</b>&nbsp;SOAP_ENV__Detail); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>fault<tt>-&gt;</tt>SOAP_ENV__Detail<tt>-&gt;</tt>__type = SOAP_TYPE_ns1__myStackDataType; // stack type <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>fault<tt>-&gt;</tt>SOAP_ENV__Detail<tt>-&gt;</tt>fault = sp; // point to stack <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>fault<tt>-&gt;</tt>SOAP_ENV__Detail<tt>-&gt;</tt>__any = NULL; // no other XML data <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>fault<tt>-&gt;</tt>detail = (<b>struct</b>&nbsp;SOAP_ENV__Detail*)soap_malloc(soap, sizeof(<b>struct</b>&nbsp;SOAP_ENV__Detail); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>fault<tt>-&gt;</tt>detail<tt>-&gt;</tt>__type = SOAP_TYPE_ns1__myStackDataType; // stack type <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>fault<tt>-&gt;</tt>detail<tt>-&gt;</tt>fault = sp; // point to stack <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>fault<tt>-&gt;</tt>detail<tt>-&gt;</tt>__any = NULL; // no other XML data <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_FAULT; // return from service operation call
</td></tr></table><br></i>
When <i>soap_receiver_fault</i> allocates a fault struct, this data is removed with the <i>soap_end</i> call (or <i>soap_dealloc</i>).
Note that the <i>soap_receiver_fault</i> function is called to allocate the fault struct and set the fault string and detail
fields, i.e. <i>soap_receiver_fault(soap, "Stack dump", NULL)</i>. The advantage is that this is independent of SOAP 1.1 and
SOAP 1.2.  However, setting the custom detail fields requires inspecting the SOAP version used, using the <i>soap</i><tt>-&gt;</tt><i>version</i>
attribute which is 1 for SOAP 1.1 and 2 for SOAP 1.2.

<div class="p"><!----></div>
Each service operation implementation in a service application can return a SOAP Fault upon an exception by returning an error code,
see Section&nbsp;<a href="#sec:example7">7.2.1</a> for details and an example.
In addition, a SOAP Fault can be returned by a service application through calling the <i>soap_send_fault</i> function.
This is useful in case the initialization of the application fails, as illustrated in the example below:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{<br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;some initialization code <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(initialization failed) <br />
&nbsp;&nbsp;&nbsp;{<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.error = soap_receiver_fault(&amp;soap, <tt>"Init&nbsp;failed"</tt>, NULL); // set the error condition (SOAP_FAULT) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_send_fault(&amp;soap); // Send SOAP Fault to client <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; // Terminate <br />
&nbsp;&nbsp;&nbsp;} <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
 <h2><a name="tth_sEc13">
13</a>&nbsp;&nbsp;<font color="#0000FF">SOAP Header Processing</font></h2><a name="sec:header">
</a>

<div class="p"><!----></div>
A predeclared standard SOAP Header data structure is generated by the gSOAP <i>soapcpp2</i> tool for exchanging SOAP
messages with SOAP Headers.
This predeclared data structure is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;SOAP_ENV__Header { };
</td></tr></table><br></i>
which declares and empty header (some C and C++ compilers don't accept empty structs, use compile flag <i>-DWITH_NOEMPTYSTRUCT</i> to avoid these errors).

<div class="p"><!----></div>
To adapt the data structure to a specific need for SOAP Header processing, a
new <i><b>struct</b>&nbsp;SOAP_ENV__Header</i> can be added to the header file input to the gSOAP
compiler.  A <i><b>class</b></i> for the SOAP Header data structure can be used instead of a <i><b>struct</b></i>.

<div class="p"><!----></div>
For example, the following header can be used for transaction control:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;SOAP_ENV__Header <br />
{ <b>char</b>&nbsp;*t__transaction; <br />
};
</td></tr></table><br></i>
with client-side code:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
... <br />
soap.header = NULL; // do not use a SOAP Header for the request (as set with soap_init) <br />
soap.actor = NULL; // do not use an actor (receiver is actor) <br />
soap_call_method(&amp;soap, ...); <br />
<b>if</b>&nbsp;(soap.header) // a SOAP Header was received <br />
&nbsp;&nbsp;&nbsp;cout  &lt;&lt;  soap.header<tt>-&gt;</tt>t__transaction; <br />
// Can reset, modify, or set soap.header here before next call <br />
soap_call_method(&amp;soap, ...); // reuse the SOAP Header of the service response for the request <br />
...
</td></tr></table><br></i>
The SOAP Web service response can include a SOAP Header with a transaction number that the client is supposed to use for the next service operation invocation to the service. Therefore, the next request includes a transaction number:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
... <br />
&lt;SOAP-ENV:Envelope ...&#62; <br />
&lt;SOAP-ENV:Header&#62; <br />
&lt;transaction xmlns="..." xsi:type="int"&#62;12345&lt;/transaction&#62; <br />
&lt;/SOAP-ENV:Header&#62; <br />
&lt;SOAP-ENV:Body&#62; <br />
... <br />
&lt;/SOAP-ENV:Body&#62; <br />
&lt;/SOAP-ENV:Envelope&#62;
</td></tr></table><br></tt>
This is just an example and the transaction control is not a feature of SOAP but can be added on by the application layer
to implement stateful transactions between clients and services.
At the client side, the <i>soap.actor</i> attribute can be set to
indicate the recipient of the header (the SOAP <tt>SOAP-ENV:actor</tt> attribute).

<div class="p"><!----></div>
A Web service can read and set the SOAP Header as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap.actor = NULL; // use this to accept all headers (default) <br />
&nbsp;&nbsp;&nbsp;soap.actor = "http://some/actor"; // accept headers destined for "http://some/actor" only <br />
&nbsp;&nbsp;&nbsp;soap_serve(&amp;soap);<br />
} <br />
... <br />
<b>int</b>&nbsp;method(<b>struct</b>&nbsp;soap *soap, ...) <br />
{<br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap<tt>-&gt;</tt>header) // a Header was received <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... = soap<tt>-&gt;</tt>header<tt>-&gt;</tt>t__transaction; <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>header = soap_malloc(<b>sizeof</b>(<b>struct</b>&nbsp;SOAP_ENV__Header)); // alloc new header <br />
...
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>header<tt>-&gt;</tt>t__transaction = ...; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
See Section&nbsp;<a href="#sec:directives">19.2</a> on how to generate WSDL with the proper method-to-header-part bindings.

<div class="p"><!----></div>
The <tt>SOAP-ENV:mustUnderstand</tt> attribute indicates the requirement that the recipient of the SOAP Header (who must
correspond to the <tt>SOAP-ENV:actor</tt> attribute when present or when the attribute has the value
<tt>SOAP-ENV:actor="http://schemas.xmlsoap.org/soap/actor/next"</tt>) MUST handle the Header part that carries the attribute.
gSOAP handles this automatically on the background. However, an application still needs to inspect the header part's value
and handle it appropriately. If a service operation in a Web service is not able to do this, it should return
<i>SOAP_MUSTUNDERSTAND</i> to indicate this failure.

<div class="p"><!----></div>
The syntax for the header file input to the gSOAP <i>soapcpp2</i> compiler is extended with a special storage qualifier <i>mustUnderstand</i>.
This qualifier can be used in the SOAP Header declaration to indicate which parts should carry a <i>SOAP-ENV:mustUnderstand="1"</i>
attribute. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;SOAP_ENV__Header <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*t__transaction; <br />
&nbsp;&nbsp;&nbsp;mustUnderstand <b>char</b>&nbsp;*t__authentication; <br />
};
</td></tr></table><br></i>
When both fields are set and <i>soap.actor="http://some/actor"</i> then the message contains:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;SOAP-ENV:Envelope ...&#62; <br />
&lt;SOAP-ENV:Header&#62; <br />
&lt;transaction xmlns="..."&#62;5&lt;/transaction&#62; <br />
&lt;authentication xmlns="..." <br />
&nbsp;&nbsp;&nbsp;SOAP-ENV:actor="http://some/actor" SOAP-ENV:mustUnderstand="1"&#62;XX <br />
&lt;/authentication&#62; <br />
&lt;/SOAP-ENV:Header&#62; <br />
&lt;SOAP-ENV:Body&#62; <br />
... <br />
&lt;/SOAP-ENV:Body&#62; <br />
&lt;/SOAP-ENV:Envelope&#62;
</td></tr></table><br></tt>

<div class="p"><!----></div>
 <h2><a name="tth_sEc14">
14</a>&nbsp;&nbsp;<font color="#0000FF">MIME Attachments</font></h2><a name="sec:MIME">
</a>

<div class="p"><!----></div>
The gSOAP toolkit supports MIME attachments as per SOAP with Attachments (SwA)
specification (http://www.w3.org/TR/SOAP-attachments). In the following
discussion, MIME attachment data is assumed to be resident in memory for
sending operations and MIME attachments received will be stored in memory. MTOM
and DIME attachments on the other hand can be streamed and therefore MTOM/DIME
attachment data does not need to be stored in memory, see
Section&nbsp;<a href="#sec:DIME">15</a> and&nbsp;<a href="#sec:MTOM">16</a>.

<div class="p"><!----></div>
Transmitting multipart/related MIME attachments with a SOAP/XML message is
accomplished with two functions, <i>soap_set_mime</i> and
<i>soap_set_mime_attachment</i>. The first function is for initialization
purposes and the latter function is used to specify meta data and content data
for each attachment.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc14.1">
14.1</a>&nbsp;&nbsp;<font color="#0000FF">Sending a Collection of MIME Attachments (SwA)</font></h3>

<div class="p"><!----></div>
The following functions should be used to set up a collection of
multipart/related MIME attachments for transmission with a SOAP/XML message.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function</b></font> </td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;soap_set_mime(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*boundary, <b>const</b>&nbsp;<b>char</b>&nbsp;*start)</i> </td></tr>
<tr><td align="left">This function must be called first to initialize MIME attachment send operations (receives are automatic). The function specifies a MIME boundary and start content ID used for the SOAP message body. When <i>boundary</i> is NULL, an appropriate MIME boundary will be choosen (important: boundaries cannot occur in the SOAP/XML message and cannot occur in any of the MIME attachments content). When a specific boundary value is provided, gSOAP will NOT verify that the boundary is valid. When <i>start</i> is NULL, the start ID of the SOAP message is <tt>&lt;</tt><tt>SOAP-ENV:Envelope</tt><tt>&gt;</tt>.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap_set_mime_attachment(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*ptr, size_t size, <b>enum</b>&nbsp;soap_mime_encoding encoding, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>const</b>&nbsp;<b>char</b>&nbsp;*location, <b>const</b>&nbsp;<b>char</b>&nbsp;*description)</i> </td></tr>
<tr><td align="left">This function adds a new attachment to the list of attachments, where <i>ptr</i> and <i>size</i> refer to the block of memory that holds the attachment data. The <i>encoding</i> parameter specifies the content encoding of this block, where the value of <i>encoding</i> is one of <i>SOAP_MIME_7BIT</i>, <i>SOAP_MIME_8BIT</i>, <i>SOAP_MIME_BINARY</i>, <i>SOAP_MIME_QUOTED_PRINTABLE</i>, <i>SOAP_MIME_BASE64</i>, <i>SOAP_MIME_IETF_TOKEN</i>, or <i>SOAP_MIME_X_TOKEN</i>. These constants reflect the content encoding defined in RFC2045 and you MUST adhere to the content encoding rules defined by RFC2045. When in doubt, use <i>SOAP_MIME_BINARY</i>, since this encoding type covers any content. The mandatory <i>type</i> string parameter is the MIME type of the data. The <i>id</i> string parameter is the content ID of the MIME attachment. The optional <i>location</i> string parameter is the content location of the attachment. The optional <i>description</i> string parameter holds a textual description of the attachment (it may not contain any control characters). All parameter values are copied, except <i>ptr</i> which must point to a valid location of the attachment data during the transfer.
The value <i>SOAP_OK</i> is returned when the attachment was added. Otherwise a gSOAP error code is returned.
</td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;soap_clr_mime(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Disables MIME attachments, e.g.&nbsp;to avoid MIME attachments to be part of a SOAP Fault response message. </td></tr></table>

</td></tr></table><br></span>
When providing a MIME boundary with <i>soap_set_mime</i>, you have to make
sure the boundary cannot match any SOAP/XML message content.
Or you can simply pass NULL and let gSOAP select a safe boundary for you.

<div class="p"><!----></div>
The internal list of attachments is destroyed with <i>soap_end</i>, you should
call this function sometime after the message exchange was completed (the
content of the block of memory referred to by the <i>ptr</i> parameter is
unaffected).

<div class="p"><!----></div>
The following example shows how a multipart/related HTTP message with three
MIME attachments is set up and transmitted to a server. The first attachment
contains the SOAP message. The second and third attachments contain image data.
In this example we let the SOAP message body refer to the attachments using
<tt>href</tt> attributes.  The <i><b>struct</b>&nbsp;claim__form</i> data type includes a
definition of a <i>href</i> attribute for this purpose.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;claim__form form1, form2; <br />
form1.href = <tt>"cid:claim061400a.tiff@claiming-it.com"</tt>; <br />
form2.href = <tt>"cid:claim061400a.jpeg@claiming-it.com"</tt>; <br />
/* initialize and enable MIME */ <br />
soap_set_mime(soap, <tt>"MIME_boundary"</tt>, <tt>"&lt;claim061400a.xml@claiming-it.com&gt;"</tt>); <br />
/* add a base64 encoded tiff image (tiffImage points to base64 data) */ <br />
soap_set_mime_attachment(soap, tiffImage, tiffLen, SOAP_MIME_BASE64, <tt>"image/tiff"</tt>, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<tt>"&lt;claim061400a.tiff@claiming-it.com&gt;"</tt>, NULL, NULL); <br />
/* add a raw binary jpeg image (jpegImage points to raw data) */ <br />
soap_set_mime_attachment(soap, jpegImage, jpegLen, SOAP_MIME_BINARY, <tt>"image/jpeg"</tt>, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<tt>"&lt;claim061400a.jpeg@claiming-it.com&gt;"</tt>, NULL, NULL); <br />
/* send the forms as MIME attachments with this invocation */ <br />
<b>if</b>&nbsp;(soap_call_claim__insurance_claim_auto(soap, form1, form2, ...)) <br />
&nbsp;&nbsp;&nbsp;// an error occurred <br />
<b>else</b><br />
&nbsp;&nbsp;&nbsp;// process response
</td></tr></table><br></i>
Note: the above example assumes that the boundary <tt>MIME_boundary</tt> does not match any part of the SOAP/XML message.

<div class="p"><!----></div>
The <i>claim__form</i> struct is declared in the gSOAP header file as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;claim__form <br />
{ @<b>char</b>&nbsp;*href; <br />
};
</td></tr></table><br></i>	
This data type defines the parameter data of the operation. The claim forms in
the SOAP/XML message consist of <tt>href</tt>s to the claim forms attached.  The
produced message is similar to the last example shown in the SOAP with
Attachments specification (http://www.w3.org/TR/SOAP-attachments).  Note that
the use of <tt>href</tt> or other attributes for referring to the MIME attachments
is optional according to the SwA standard.

<div class="p"><!----></div>
To associate MIME attachments with the request and response of a service operation in the generated WSDL, please see Section&nbsp;<a href="#sec:MIMEWSDL">16.1</a>.

<div class="p"><!----></div>
The server-side code to transmit MIME attachments back to a client is similar:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;claim__insurance_claim_auto(<b>struct</b>&nbsp;soap *soap, ...) <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_set_mime(soap, NULL, NULL); // enable MIME<br />
&nbsp;&nbsp;&nbsp;// add a HTML document (htmlDoc points to data, where the HTML doc is stored in compliance with 7bit encoding RFC2045) <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_set_mime_attachment(soap, htmlDoc, strlen(htmlDoc), SOAP_MIME_7BIT, <tt>"text/html"</tt>, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<tt>"&lt;claim061400a.html@claiming-it.com&gt;"</tt>, NULL, NULL)) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_clr_mime(soap); // don't want fault with attachments <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap<tt>-&gt;</tt>error; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
It is also possible to attach data to a SOAP fault message.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution:</b></font> DIME in MIME is supported. However, gSOAP will not verify whether
the MIME boundary is present in the DIME attachments and therefore will not
select a boundary that is guaranteed to be unique. Therefore, you must provide
a MIME boundary with <i>soap_set_mime</i> that is unique when using DIME in
MIME.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc14.2">
14.2</a>&nbsp;&nbsp;<font color="#0000FF">Retrieving a Collection of MIME Attachments (SwA)</font></h3>

<div class="p"><!----></div>
MIME attachments are automatically parsed and stored in memory.
After receiving a set of MIME attachments, either at the client-side or
the server-side, the list of MIME attachments can be traversed to extract
meta data and the attachment content. The first attachment in the collection of
MIME attachments always contains meta data about the SOAP message
itself (because the SOAP message was processed the attachment does not contain
any useful data).

<div class="p"><!----></div>
To traverse the list of MIME attachments in C, you use a loop similar to:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap_multipart *attachment; <br />
<b>for</b>&nbsp;(attachment = soap.mime.list; attachment; attachment = attachment<tt>-&gt;</tt>next) <br />
{ <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"MIME&nbsp;attachment:\n"</tt>); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"Memory=%p\n"</tt>, (*attachment).ptr); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"Size=%ul\n"</tt>, (*attachment).size); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"Encoding=%d\n"</tt>, (<b>int</b>)(*attachment).encoding); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"Type=%s\n"</tt>, (*attachment).type?(*attachment).type:"null"); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"ID=%s\n"</tt>, (*attachment).id?(*attachment).id:"null"); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"Location=%s\n"</tt>, (*attachment).location?(*attachment).location:"null"); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"Description=%s\n"</tt>, (*attachment).description?(*attachment).description:"null"); <br />
}
</td></tr></table><br></i>
C++ programmers can use an iterator instead, as in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>for</b>&nbsp;(soap_multipart::iterator attachment = soap.mime.begin(); attachment != soap.mime.end(); ++attachment) <br />
{ <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "MIME attachment:" <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "Memory=" <tt>&lt;&lt;</tt> (<b>void</b>*)(*attachment).ptr <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "Size=" <tt>&lt;&lt;</tt> (*attachment).size <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> &#203;ncoding=" <tt>&lt;&lt;</tt> (*attachment).encoding <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "Type=" <tt>&lt;&lt;</tt> ((*attachment).type?(*attachment).type:"null") <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "ID=" <tt>&lt;&lt;</tt> ((*attachment).id?(*attachment).id:"null") <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "Location=" <tt>&lt;&lt;</tt> ((*attachment).location?(*attachment).location:"null") <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "Description=" <tt>&lt;&lt;</tt> ((*attachment).description?(*attachment).description:"null") <tt>&lt;&lt;</tt> endl; <br />
}
</td></tr></table><br></i>
Note: keep in mind that the first attachment is associated with the SOAP
message and you may want to ignore it.

<div class="p"><!----></div>
A call to <i>soap_end</i> removes all of the received MIME data. To preserve an
attachment in memory, use <i>soap_unlink</i> on the <i>ptr</i> field of the
<i>soap_multipart</i> struct. Recall that the <i>soap_unlink</i> function is
commonly used to prevent deallocation of deserialized data.

<div class="p"><!----></div>
 <h2><a name="tth_sEc15">
15</a>&nbsp;&nbsp;<font color="#0000FF">DIME Attachments</font></h2><a name="sec:DIME">
</a>

<div class="p"><!----></div>
The gSOAP toolkit supports DIME attachments as per DIME specification, see
http://msdn.microsoft.com/library/en-us/dnglobspec/html/draft-nielsen-dime-02.txt

<div class="p"><!----></div>
Applications developed with gSOAP can transmit binary DIME attachments with or
without streaming messages. Without streaming, all data is stored and retrieved in
memory, which can be prohibitive when transmitting large files on small
devices. The maximum DIME attachment size is limited to 8 MB by default as set with <i>SOAP_MAXDIMESIZE</i> in <i>stdsoap2.h</i>. In contrast, with DIME streaming, data handlers are used to pass the
data to and from a resource, such as a file or device.  With DIME output
streaming, raw binary data is send from a data source in chunks on the fly
without buffering the entire content to save memory. With DIME input streaming,
raw binary data will be passed to data handlers (callbacks).

<div class="p"><!----></div>
	     <h3><a name="tth_sEc15.1">
15.1</a>&nbsp;&nbsp;<font color="#0000FF">Sending a Collection of DIME Attachments</font></h3>

<div class="p"><!----></div>
The following functions can be used to explicitly set up a collection of
DIME attachments for transmission with a SOAP/XML message body.
The attachments can be streamed, as described in
Section&nbsp;<a href="#sec:DIMEstreaming">15.4</a>.  Without streaming, each attachment must refer
to a block of data in memory.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function</b></font> </td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;soap_set_dime(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">This function must be called first to initialize DIME attachment send operations (receives are automatic).
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap_set_dime_attachment(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*ptr, size_t size, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>unsigned</b>&nbsp;<b>short</b>&nbsp;optype, <b>const</b>&nbsp;<b>char</b>&nbsp;*option)</i> </td></tr>
<tr><td align="left">This function adds a new attachment to the list of attachments, where <i>ptr</i> and <i>size</i> refer to the block of memory that holds the attachment data (except when DIME streaming callback handlers are used as described in Section&nbsp;<a href="#sec:DIMEstreaming">15.4</a>. The <i>type</i> string parameter is the MIME type of the data. The <i>id</i> string parameter is the content ID of the DIME attachment. The <i>option</i> string parameter holds optional text (gSOAP supports DIME options, but it can send only one) and <i>optype</i> is a user-defined option type (as per DIME option specification format). All parameter values are copied, except <i>ptr</i>.
The value <i>SOAP_OK</i> is returned when the attachment was added. Otherwise a gSOAP error code is returned.
</td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;soap_clr_dime(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Disables DIME attachments, unless the serialized SOAP message contains attachments for transmission.
</td></tr></table>

</td></tr></table><br></span>
These functions allow DIME attachments to be added without requiring message
body references. This is also referred to as the open DIME attachment style.
The closed attachment style requires all DIME attachments to be referenced from
the SOAP message body with <tt>href</tt> (or similar) references. For the closed
style, gSOAP supports an automatic binary data serialization method, see
Section&nbsp;<a href="#sec:DIMEbinary">15.3</a>.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc15.2">
15.2</a>&nbsp;&nbsp;<font color="#0000FF">Retrieving a Collection of DIME Attachments</font></h3>

<div class="p"><!----></div>
DIME attachments are automatically parsed and stored in memory (or passed to
the streaming handlers, when applicable).  After receiving a set of DIME
attachments, either at the client-side or the server-side, the list of DIME
attachments can be traversed to extract meta data and the attachment content.

<div class="p"><!----></div>
To traverse the list of DIME attachments in C, you use a loop similar to:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap_multipart *attachment; <br />
<b>for</b>&nbsp;(attachment = soap.dime.list; attachment; attachment = attachment<tt>-&gt;</tt>next) <br />
{ <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"DIME&nbsp;attachment:\n"</tt>); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"Memory=%p\n"</tt>, (*attachment).ptr); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"Size=%ul\n"</tt>, (*attachment).size); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"Type=%s\n"</tt>, (*attachment).type?(*attachment).type:"null"); <br />
&nbsp;&nbsp;&nbsp;printf(<tt>"ID=%s\n"</tt>, (*attachment).id?(*attachment).id:"null"); <br />
}
</td></tr></table><br></i>
C++ programmers can use an iterator instead, as in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>for</b>&nbsp;(soap_multipart::iterator attachment = soap.dime.begin(); attachment != soap.dime.end(); ++attachment) <br />
{ <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "DIME attachment:" <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "Memory=" <tt>&lt;&lt;</tt> (<b>void</b>*)(*attachment).ptr <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "Size=" <tt>&lt;&lt;</tt> (*attachment).size <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "Type=" <tt>&lt;&lt;</tt> ((*attachment).type?(*attachment).type:"null") <tt>&lt;&lt;</tt> endl; <br />
&nbsp;&nbsp;&nbsp;cout <tt>&lt;&lt;</tt> "ID=" <tt>&lt;&lt;</tt> ((*attachment).id?(*attachment).id:"null") <tt>&lt;&lt;</tt> endl; <br />
}
</td></tr></table><br></i>
The <i>options</i> field is available as well. The <i>options</i> content is
formatted according to the DIME specification: the first two bytes are reserved
for the option type, the next two bytes store the size of the option data,
followed by the (binary) option data.

<div class="p"><!----></div>
A call to <i>soap_end</i> removes all of the received DIME data. To preserve an
attachment in memory, use <i>soap_unlink</i> on the <i>ptr</i> field of the
<i>soap_multipart</i> struct. Recall that the <i>soap_unlink</i> function is
commonly used to prevent deallocation of deserialized data.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc15.3">
15.3</a>&nbsp;&nbsp;<font color="#0000FF">Serializing Binary Data in DIME</font></h3><a name="sec:DIMEbinary">
</a>

<div class="p"><!----></div>
Binary data stored in extended <tt>xsd:base64Binary</tt> and <tt>xsd:hexBinary</tt>
types can be serialized and deserialized as DIME attachments. These attachments
will be transmitted prior to the sequence of secondary DIME attachments defined
by the user with <i>soap_set_dime_attachment</i> as explained in the
previous section. The serialization process is automated and DIME attachments
will be send even when <i>soap_set_dime</i> or
<i>soap_set_dime_attachment</i> are not used.

<div class="p"><!----></div>
The <tt>xsd:base64Binary</tt> XSD type is defined in gSOAP as a struct or class by
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;xsd__base64Binary <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; // pointer to raw binary data <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; // size of the block of data <br />
};
</td></tr></table><br></i>
To enable serialization of the data in DIME, we extend this type with three
additional fields:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;xsd__base64Binary <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*id; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*options; <br />
};
</td></tr></table><br></i>
The three additional fields consist of an <i>id</i> field for attachment
referencing (typically a content id (CID) or UUID), a <i>type</i> field to
specify the MIME type of the binary data, and an <i>options</i> field to
piggy-back additional information with a DIME attachment.  The order of the
declaration of the fields is significant. In addition, no other fields or
methods may be declared before any of these fields in the struct/class, but
additional fields and methods may appear after the field declarations. An
extended <i>xsd__hexBinary</i> declaration is similar.

<div class="p"><!----></div>
The <i>id</i> and <i>type</i> fields contain text. The set the DIME-specific
options field, you can use the <i>soap_dime_option</i> function: <br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>char</b>&nbsp;*soap_dime_option(<b>struct</b>&nbsp;soap *soap, <b>unsigned</b>&nbsp;<b>short</b>&nbsp;type, <b>const</b>&nbsp;<b>char</b>&nbsp;*option)
</td></tr></table><br></i>
returns a string with this encoding. For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;xsd__base64Binary image; <br />
image.__ptr = ...; <br />
image.__size = ...; <br />
image.id = <tt>"uuid:09233523-345b-4351-b623-5dsf35sgs5d6"</tt>; <br />
image.type = <tt>"image/jpeg"</tt>; <br />
image.options = soap_dime_option(soap, 0, <tt>"My&nbsp;wedding&nbsp;picture"</tt>);
</td></tr></table><br></i>
When either the <i>id</i> or <i>type</i> field values are non-NULL at run time,
the data will be serialized as a DIME attachment. The SOAP/XML message refers
to the attachments using <tt>href</tt> attributes. This generally works will with
SOAP RPC, because <tt>href</tt> attributes are permitted. However, with document/literal style the referencing mechanism must be explicitly defined
in the schema of the binary type. The gSOAP
declaration of an extended binary type is
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__myBinaryDataType <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*id; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*options; <br />
};
</td></tr></table><br></i>
C++ programmers can use inheritance instead of textual extension required in C, as in
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>class</b>&nbsp;xsd__base64Binary <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
}; <br />
<b>class</b>&nbsp;ns__myBinaryDataType : xsd__base64Binary <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*id; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*options; <br />
};
</td></tr></table><br></i>
This defines an extension of <tt>xsd:base64Binary</tt>, such that the data can be 
serialized as DIME attachments using <tt>href</tt> attributes for referencing.
When a different attribute name is in fact used, it must be explicitly defined:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap WSref schema import: http://schemas.xmlsoap.org/ws/2002/04/reference/ <br />
<b>struct</b>&nbsp;ns__myBinaryDataType <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*id; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*options; <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;*WSref__location; <br />
};
</td></tr></table><br></i>
The example above uses the <tt>location</tt> attribute defined in the content reference schema, as defined in one of the vendor's specific WSDL extensions for DIME (http://www.gotdotnet.com/team/xml_wsspecs/dime/WSDL-Extension-for-DIME.htm).

<div class="p"><!----></div>
When receiving DIME attachments, the DIME meta data and binary data content is
stored in binary data types only when the XML parts of the message uses
<tt>href</tt> attributes to refer to these attachments. The gSOAP toolkit may
support automatic (de)serialization with other user-defined (or WSDL-defined)
attributes in future releases.

<div class="p"><!----></div>
Messages may contain binary data that references external resources not
provided as attachments. In that case, the <i>__ptr</i> field is NULL and the
<i>id</i> field refers to the external data source.

<div class="p"><!----></div>
The <i>dime_id_format</i> attribute of the current gSOAP run-time context
can be set to the default format of DIME id fields.  The format string MUST
contain a <i>%d</i> format specifier (or any other <i><b>int</b></i>-based format
specifier). The value of this specifier is a non-negative integer, with zero
being the value of the DIME attachment id for the SOAP message.  For example,
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap;<br />
soap_init(&amp;soap); <br />
soap.dime_id_format = <tt>"uuid:09233523-345b-4351-b623-5dsf35sgs5d6-%x"</tt>; <br />
</td></tr></table><br></i>
As a result, all attachments with a NULL <i>id</i> field will use a
gSOAP-generated id value based on the format string.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution:</b></font> Care must be taken not to introduce duplicate content id values,
when assigning content id values to the id fields of DIME extended binary data
types. Content ids must be unique.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc15.4">
15.4</a>&nbsp;&nbsp;<font color="#0000FF">Streaming DIME</font></h3><a name="sec:DIMEstreaming">
</a>

<div class="p"><!----></div>
Streaming DIME is achieved with callback functions to fetch and store data
during transmission.  Three function callbacks for streaming DIME output and
three callbacks for streaming DIME input are available.

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Callback (function pointer)</b></font> </td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;*(*soap.fdimereadopen)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*options)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time DIME attachment sender to start reading from a
(binary) data source for outbound transmission. The content will be read from the
application's data source in chunks using the <i>fdimeread</i> callback and
streamed into the SOAP/XML/DIME output stream. The <i>handle</i> contains the
value of the <i>__ptr</i> field of an attachment struct/class, which could be a
pointer to specific information such as a file descriptor or a pointer to a
string to be passed to this callback.  Both <i>__ptr</i> and <i>__size</i>
fields should have been set by the application prior to the serialization of
the content. The <i>id</i>, <i>type</i>, and <i>options</i> arguments are the DIME
id, type, and options, respectively. The callback should return <i>handle</i>,
or another pointer value which will be passed as a handle to <i>fdimeread</i>
and <i>fdimereadclose</i>.  The callback should return NULL and set
<i>soap</i><tt>-&gt;</tt><i>error</i> when an error occurred. The callback should return
NULL (and not set <i>soap</i><tt>-&gt;</tt><i>error</i>) when this particular DIME
attachment is not to be streamed.
</td></tr>
<tr><td align="left"><i>size_t (*soap.fdimeread)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>char</b>&nbsp;*buf, size_t len)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time DIME attachment sender to read more data from a
(binary) data source for streaming into the output stream.  The <i>handle</i>
contains the value returned by the <i>fdimereadopen</i> callback.  The <i>buf</i>
argument is the buffer of length <i>len</i> into which a chunk of data should be
stored.  The actual amount of data stored in the buffer may be less than
<i>len</i> and this amount should be returned by the application.  A return value
of 0 indicates an error (the callback may set <i>soap</i><tt>-&gt;</tt><i>errnum</i> to errno).
The <i>__size</i> field of the attachment
struct/class should have been set by the application prior to the serialization
of the content.  The value of <i>__size</i> indicates the total size of the
content to be transmitted.  When the <i>__size</i> is zero then DIME chunked
transfers can be used under certain circumstances to stream content without
prior determination of attachment size, see Section&nbsp;<a href="#sec:dimechunking">15.5</a> below.
</td></tr>
<tr><td align="left"><i><b>void</b>(*soap.fdimereadclose)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time DIME attachment sender at the end of the
streaming process to close the data source.  The <i>handle</i> contains the
value returned by the <i>fdimereadopen</i> callback.  The <i>fdimewriteclose</i>
callback is called after successfully transmitting the data or when an error
occurred.
</td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;*(*soap.fdimewriteopen)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*options)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time DIME attachment receiver to start writing an
inbound DIME attachment to an application's data store. The content is streamed
into an application data store through multiple <i>fdimewrite</i> calls from the
gSOAP attachment receiver.  The <i>id</i>, <i>type</i>, and <i>options</i>
arguments are the DIME id, type, and options respectively. The callback should
return a handle which is passed to the <i>fdimewrite</i> and
<i>fdimewriteclose</i> callbacks. The <i>__ptr</i> field of the attachment
struct/class is set to the value of this handle. The <i>__size</i> field is set
to the total size of the attachment after receiving the entire content. The size
is unknown in advance because DIME attachments may be chunked.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fdimewrite)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>const</b>&nbsp;<b>char</b>&nbsp;*buf, size_t len)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time DIME attachment receiver to write part of
an inbound DIME attachment to an application's data store.
The <i>handle</i>
contains the value returned by the <i>fdimewriteopen</i> callback.  The <i>buf</i>
argument contains the data of length <i>len</i>.
The callback should return a gSOAP error code (e.g.&nbsp;<i>SOAP_OK</i> when no error occurred).
</td></tr>
<tr><td align="left"><i><b>void</b>(*soap.fdimewriteclose)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time DIME attachment receiver at the end of the
streaming process to close the data store.  The <i>fdimewriteclose</i> callback
is called after successfully receiving the data or when an error occurred.  The
<i>handle</i> contains the value returned by the <i>fdimewriteopen</i> callback.
</td></tr></table>

</td></tr></table><br></span>
In addition, a <i><b>void</b>*user</i> field in the <i><b>struct</b>&nbsp;soap</i> data structure
is available to pass user-defined data to the callbacks.  This way, you can set
<i>soap.user</i> to point to application data that the callbacks need such as a
file name for example.

<div class="p"><!----></div>
The following example illustrates the client-side initialization of an image
attachment struct to stream a file into a DIME attachment:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;xsd__base64Binary image; <br />
&nbsp;&nbsp;&nbsp;FILE *fd; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;stat sb; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!fstat(fileno(fd), &amp;sb) &amp;&amp; sb.st_size  &gt;  0) <br />
&nbsp;&nbsp;&nbsp;{ // because we can get the length of the file, we can stream it <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.fdimereadopen = dime_read_open; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.fdimereadclose = dime_read_close; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.fdimeread = dime_read; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;image.__ptr = (<b>unsigned</b>&nbsp;<b>char</b>*)fd; // must set to non-NULL (this is our fd handle which we need in the callbacks) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;image.__size = sb.st_size; // must set size <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;{ // don't know the size, so buffer it <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;size_t i; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;c; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;image.__ptr = (<b>unsigned</b>&nbsp;<b>char</b>*)soap_malloc(&amp;soap, MAX_FILE_SIZE); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  MAX_FILE_SIZE; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;((c = fgetc(fd)) == EOF) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;image.__ptr[i] = c; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fclose(fd); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;image.__size = i; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;image.type = "image/jpeg"; <br />
&nbsp;&nbsp;&nbsp;image.options = soap_dime_option(&amp;soap, 0, "My picture"); <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__method(&amp;soap, ...); <br />
&nbsp;&nbsp;&nbsp;... <br />
} <br />
<b>void</b>&nbsp;*dime_read_open(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*options) <br />
{ <b>return</b>&nbsp;handle; <br />
} <br />
<b>void</b>&nbsp;dime_read_close(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle) <br />
{ fclose((FILE*)handle); <br />
} <br />
size_t dime_read(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>char</b>&nbsp;*buf, size_t len) <br />
{ <b>return</b>&nbsp;fread(buf, 1, len, (FILE*)handle); <br />
}
</td></tr></table><br></i>
The following example illustrates the streaming of a DIME attachment into a file by a client:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap.fdimewriteopen = dime_write_open; <br />
&nbsp;&nbsp;&nbsp;soap.fdimewriteclose = dime_write_close; <br />
&nbsp;&nbsp;&nbsp;soap.fdimewrite = dime_write; <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__method(&amp;soap, ...); <br />
&nbsp;&nbsp;&nbsp;... <br />
} <br />
<b>void</b>&nbsp;*dime_write_open(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*options) <br />
{ <br />
&nbsp;&nbsp;&nbsp;FILE *handle = fopen("somefile", "wb"); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!handle) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>error = SOAP_EOF; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>errnum = errno; // get reason <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;(<b>void</b>*)handle; <br />
} <br />
<b>void</b>&nbsp;dime_write_close(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle) <br />
{ fclose((FILE*)handle); <br />
} <br />
<b>int</b>&nbsp;dime_write(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>const</b>&nbsp;<b>char</b>&nbsp;*buf, size_t len) <br />
{ <br />
&nbsp;&nbsp;&nbsp;size_t nwritten; <br />
&nbsp;&nbsp;&nbsp;<b>while</b>&nbsp;(len) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;nwritten = fwrite(buf, 1, len, (FILE*)handle); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!nwritten) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>errnum = errno; // get reason <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_EOF; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;len -= nwritten; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buf += nwritten; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
Note that compression can be used with DIME to compress the entire message.
However, compression requires buffering to determine the HTTP content length
header, which cancels the benefits of streaming DIME. To avoid this, you should
use chunked HTTP (with the output-mode <i>SOAP_IO_CHUNK</i> flag) with
compression and streaming DIME. At the server side, when you set
<i>SOAP_IO_CHUNK</i> before calling <i>soap_serve</i>, gSOAP will
automatically revert to buffering (<i>SOAP_IO_STORE</i> flag is set).  You can
check this flag with <i>(soap-&#62;omode &amp; SOAP_IO) == SOAP_IO_CHUNK</i> to see
if the client accepts chunking. More information about streaming chunked DIME
can be found in Section&nbsp;<a href="#sec:dimechunking">15.5</a>.

<div class="p"><!----></div>
<font color="#FF0000"><b>C</b></font>aution: The <i>options</i> field is a DIME-specific data structure,
consisting of a 4 byte header containing the option type info (hi byte, lo
byte), option string length (hi byte, lo byte), followed by a non-<tt>'\0'</tt>
terminated string. The gSOAP DIME handler recognizes one option at most.

<div class="p"><!----></div>
		     <h3><a name="tth_sEc15.5">
15.5</a>&nbsp;&nbsp;<font color="#0000FF">Streaming Chunked DIME</font></h3><a name="sec:dimechunking">
</a>

<div class="p"><!----></div>
gSOAP automatically handles inbound chunked DIME attachments (streaming or
non-streaming).  To transmit outbound DIME attachments, the attachment sizes
MUST be determined in advance to calculate HTTP message length required to
stream DIME over HTTP.  However, gSOAP also supports the transmission of
outbound chunked DIME attachments without prior determination of DIME
attachment sizes when certain conditions are met.  These conditions require
either non-HTTP transport (use the output-mode <i>SOAP_ENC_XML</i> flag), or
chunked HTTP transport (use the output-mode <i>SOAP_IO_CHUNK</i> flag).  You
can also use the <i>SOAP_IO_STORE</i> flag (which is also used automatically
with compression to determine the HTTP content length header) but that cancels
the benefits of streaming DIME.

<div class="p"><!----></div>
To stream chunked DIME, set the <i>__size</i> field of an attachment to zero
and enable HTTP chunking.  The DIME <i>fdimeread</i> callback then fetches data
in chunks and it is important to fill the entire buffer unless the end of the
data has been reached and the last chunk is to be send.  That is,
<i>fdimeread</i> should return the value of the last <i>len</i> parameter and
fill the entire buffer <i>buf</i> for all chunks except the last.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc15.6">
15.6</a>&nbsp;&nbsp;<font color="#0000FF">WSDL Bindings for DIME Attachments</font></h3>

<div class="p"><!----></div>
The <i>wsdl2h</i> WSDL parser recognizes DIME attachments and produces an
annotated header file. Both open and closed layouts are supported for
transmitting DIME attachments. For closed formats, all DIME attachments must be
referenced from the SOAP message, e.g.&nbsp;using hrefs with SOAP encoding and using
the application-specific reference attribute included in the <i>base64Binary</i>
struct/class for doc/lit.

<div class="p"><!----></div>
The gSOAP compiler <i>soapcpp2</i> does not produce a WSDL with DIME extensions.
DIME is an older binary format that has no WSDL protocol support, unlike MIME
and MTOM.

<div class="p"><!----></div>
 <h2><a name="tth_sEc16">
16</a>&nbsp;&nbsp;<font color="#0000FF">MTOM Attachments</font></h2><a name="sec:MTOM">
</a>

<div class="p"><!----></div>
MTOM (Message Transmission Optimization Mechanism) is a relatively new format
for transmitting attachments with SOAP messages (see
<a href="http://www.w3.org/TR/soap12-mtom"><tt>http://www.w3.org/TR/soap12-mtom</tt></a>). MTOM is a W3C working draft as of this
writing. MTOM attachments are essentially MIME attachments with standardized
mechanisms for cross referencing attachments from the SOAP body, which is
absent in (plain) MIME attachments and optional with DIME attachments.

<div class="p"><!----></div>
Unlike the name suggests, the speed by which attached data is transmitted is
not increased compared to MIME, DIME, or even XML encoded base64 data (at least
the performance differences in gSOAP will be small). The advantage of the
format is the standardized attachment reference mechanism, which should improve
interoperability.

<div class="p"><!----></div>
The MTOM specification mandates SOAP 1.2 and the use of the XOP namespace. The
XOP Include element <tt>xop:Include</tt> is used to reference attachment(s) from the SOAP message body.

<div class="p"><!----></div>
Because references from within the SOAP message body to attachments are
mandatory with MTOM, the implementation of the serialization and deserialization of MTOM
MIME attachments in gSOAP uses the extended binary type comparable to DIME support in gSOAP. This binary type is predefined in the <i>import/xop.h</i> file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap xop schema import: http://www.w3.org/2004/08/xop/include <br />
<b>struct</b>&nbsp;_xop__Include <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>char</b>&nbsp;*__ptr; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*id; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*options; <br />
}; <br />
<b>typedef</b>&nbsp;<b>struct</b>&nbsp;_xop__Include _xop__Include;
</td></tr></table><br></i>
The additional <i>id</i>, <i>type</i>, and <i>option</i> fields
enable MTOM attachments for the data pointed to by <i>__ptr</i> of size <i>__size</i>. The process for sending and receiving MTOM XOP
attachments is fully automated.
The <i>id</i> field references the attachment (typically a content id CID or UUID). When set to NULL, gSOAP assigns a unique CID. The <i>type</i>
field specifies the required MIME type of the binary data, and the optional
<i>options</i> field can be used to piggy-back descriptive text with an attachment.  The order of the
declaration of the fields is significant.

<div class="p"><!----></div>
You can explicitly import the <i>xop.h</i> in your header file to use the MTOM attachments in your service, for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "import/soap12.h" <br />
/* alternatively, without the import above, use: <br />
//gsoap SOAP-ENV schema namespace: http://www.w3.org/2003/05/soap-envelope <br />
//gsoap SOAP-ENC schema namespace: http://www.w3.org/2003/05/soap-encoding <br />
*/ <br />
#import "import/xop.h" <br />
#import "import/xmime5.h" <br />
<br />
//gsoap x schema namespace: http://my.first.mtom.net <br />
<b>struct</b>&nbsp;x__myData <br />
{ <br />
&nbsp;&nbsp;&nbsp;_xop__Include xop__Include; // attachment <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;*xmime5__contentType; // and its contentType <br />
}; <br />
<b>int</b>&nbsp;x__myMTOMtest(<b>struct</b>&nbsp;x__myData *in, <b>struct</b>&nbsp;x__myData *out);
</td></tr></table><br></i>
As you can see, there is really no difference between the specification of MTOM
and DIME attachments in a gSOAP header file. Except that you MUST use SOAP 1.2
and the <i>xop__Include</i> element.

<div class="p"><!----></div>
When an instance of <i>x__myDataType</i> is serialized and either or both the
<i>id</i> and <i>type</i> fields are non-NULL, the data is transmitted as MTOM
MIME attachment if the <i>SOAP_ENC_MTOM</i> flag is set in the gSOAP's soap
struct context:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap *soap = soap_new1(SOAP_ENC_MTOM);
</td></tr></table><br></i>
Without this flag, the attachments will be transmitted in DIME format
(Section&nbsp;<a href="#sec:DIME">15</a>). If your current clients and services are based on
non-streaming DIME attachments using the SOAP body reference mechanism (thus,
without using the <i>soap_set_dime_attachment</i> function) or plain base64
binary XML data elements, it is very easy to adopt MTOM by renaming the binary types to <i>xop__Include</i> and using the
<i>SOAP_ENC_MTOM</i> flag with the SOAP 1.2 namespace.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc16.1">
16.1</a>&nbsp;&nbsp;<font color="#0000FF">Generating MultipartRelated MIME Attachment Bindings in WSDL</font></h3><a name="sec:MIMEWSDL">
</a>

<div class="p"><!----></div>
To generate multipartRelated bindings in the WSDL file, use the <i>//gsoap
... service method-mime-type</i> directive (see also Section&nbsp;<a href="#sec:directives">19.2</a>. The
directive can be repeated for each attachment you want to associate with a
method's request and response messages.

<div class="p"><!----></div>
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "import/soap12.h" <br />
#import "import/xop.h" <br />
#import "import/xmime5.h" <br />
<br />
//gsoap x schema namespace: http://my.first.mtom.net <br />
<b>struct</b>&nbsp;x__myData <br />
{ <br />
&nbsp;&nbsp;&nbsp;_xop__Include xop__Include; // attachment <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;*xmime5__contentType; // and its contentType <br />
}; <br />
//gsoap x service method-mime-type: myMTOMtest text/xml <br />
<b>int</b>&nbsp;x__myMTOMtest(<b>struct</b>&nbsp;x__myData *in, <b>struct</b>&nbsp;x__myData *out);
</td></tr></table><br></i>
The <i>//gsoap x service method-mime-type</i> directive indicates that this
operation accepts <tt>text/xml</tt> MIME attachments. See the SOAP-with-Attachment
specification for the MIME types to use (for example, <tt>*/*</tt> is a wildcard).
If the operation has more than one attachment, just repeat this directive for
each attachment you want to bind to the operation.

<div class="p"><!----></div>
To bind attachments only to the request message of an operation, use
<i>//gsoap x service method-input-mime-type</i>. Similarly, to bind attachments
only to the response message of an operation, use <i>//gsoap x service
method-ouput-mime-type</i>.

<div class="p"><!----></div>
The <i>wsdl2h</i> WSDL parser recognizes MIME attachments and produces an
annotated header file. However, the ordering of MIME parts in the
multipartRelated elements is not reflected in the header file. Application
developers should adhere the standards and ensure that multipart/related
attachments are transmitted in compliance with the WSDL operation declarations.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc16.2">
16.2</a>&nbsp;&nbsp;<font color="#0000FF">Sending and Receiving MTOM Attachments</font></h3>

<div class="p"><!----></div>
A receiver must be informed to recognize MTOM attachments by setting the
<i>SOAP_ENC_MTOM</i> flag of the gSOAP context. Otherwise, the regular MIME
attachment mechanism (SwA) will be used to store attachments.

<div class="p"><!----></div>
When using <i>wsdl2h</i> to build clients and/or services, you should use the
<i>typemap.dat</i> file included in the distribution package. The
<i>typemap.dat</i> file defines the XOP namespace and XML MIME namespaces as
imported namespaces:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
xop    =  &lt; http://www.w3.org/2004/08/xop/include &gt;  <br />
xmime5 =  &lt; http://www.w3.org/2005/05/xmlmime &gt;  <br />
xmime4 =  &lt; http://www.w3.org/2004/11/xmlmime &gt; 
</td></tr></table><br></i>
The <i>wsdl2h</i> tool uses the <i>typemap.dat</i> file (see also option -t) to
convert WSDL into a gSOAP header file. In this case we don't want the
<i>wsdl2h</i> tool to read the XOP schema and translate it, since we have a
pre-defined <i>_xop__Include</i> element to handle XOP for MTOM. This
<i>_xop__Include</i> element is defined in <i>xop.h</i>. Therefore, the
bindings shown above will not translate the XOP and XML MIME schemas to code,
but generates <i>#import</i> statements instead:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "xop.h" <br />
#import "xmime5.h"
</td></tr></table><br></i>
The <i>#import</i> statements are only added for those namespaces that are
actually used by the service.

<div class="p"><!----></div>
Let's take a look at an example.
The <i>wsdl2h</i> importer generates a header file with <i>#import "xop.h"</i> from a WSDL that references XOP, for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "xop.h" <br />
#import "xmime5.h" <br />
<b>struct</b>&nbsp;ns__Data <br />
{ <br />
&nbsp;&nbsp;&nbsp;_xop__Include xop__Include; <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;*xmime5__contentType;  <br />
};
</td></tr></table><br></i>
Suppose the WSDL defines an operation:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__echoData(<b>struct</b>&nbsp;ns__Data *in, <b>struct</b>&nbsp;ns__Data *out);
</td></tr></table><br></i>
After generating the stubs/proxies with the <i>soapcpp2</i> compiler, we can invoke the stub at the client side with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap *soap = soap_new1(SOAP_ENC_MTOM); <br />
<b>struct</b>&nbsp;ns__Data data; <br />
data.xop__Include.__ptr = (<b>unsigned</b>&nbsp;<b>char</b>*)"<tt>&lt;b&gt;Hello&nbsp;world!&lt;/b&gt;</tt>"; <br />
data.xop__Include.__size = 20; <br />
data.xop__Include.id = NULL; // CID automatically generated by gSOAP engine <br />
data.xop__Include.type = "text/html"; // MIME type <br />
data.xop__Include.options = NULL; // no descriptive info added <br />
data.xmime5__contentType = "text/html"; // MIME type <br />
<b>if</b>&nbsp;(soap_call_ns__echoData(soap, endpoint, action, &amp;data, &amp;data))
&nbsp;&nbsp;&nbsp;soap_print_fault(soap, stderr);
<b>else</b><br />
&nbsp;&nbsp;&nbsp;printf("<tt>Got&nbsp;data\n</tt>"); <br />
soap_destroy(soap); // remove deserialized class instances <br />
soap_end(soap); // remove temporary and deserialized data <br />
soap_free(soap); // detach and free context
</td></tr></table><br></i>
Note that the <i>xop__Include.type</i> field must be set to transmit MTOM attachments, otherwise plain base64 XML will be used.

<div class="p"><!----></div>
At the server side, we show an example of an operation handler that just copies the input data to output:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__echoData(<b>struct</b>&nbsp;soap *soap, <b>struct</b>&nbsp;ns__Data *in, <b>struct</b>&nbsp;ns__data *out) <br />
{ <br />
&nbsp;&nbsp;&nbsp;*out = *in; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
The server must use the <i>SOAP_ENC_MTOM</i> flag to initialize the soap struct to receive and send MTOM attachments.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc16.3">
16.3</a>&nbsp;&nbsp;<font color="#0000FF">Streaming MTOM/MIME</font></h3><a name="sec:MTOMstreaming">
</a>

<div class="p"><!----></div>
Streaming MTOM/MIME is achieved with callback functions to fetch and store data
during transmission. Three function callbacks for streaming MTOM/MIME output and
three callbacks for streaming MTOM/MIME input are available.

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Callback (function pointer)</b></font> </td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;*(*soap.fmimereadopen)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*description)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time MTOM/MIME attachment sender to start reading from a
(binary) data source for outbound transmission. The content will be read from the
application's data source in chunks using the <i>fmimeread</i> callback and
streamed into the SOAP/XML/MTOM/MIME output stream. The <i>handle</i> contains the
value of the <i>__ptr</i> field of an attachment struct/class, which could be a
pointer to specific information such as a file descriptor or a pointer to a
string to be passed to this callback.  Both <i>__ptr</i> and <i>__size</i>
fields should have been set by the application prior to the serialization of
the content. The <i>id</i>, <i>type</i>, and <i>description</i> arguments are the MTOM/MIME
id, type, and description, respectively. The callback should return <i>handle</i>,
or another pointer value which will be passed as a handle to <i>fmimeread</i>
and <i>fmimereadclose</i>.  The callback should return NULL and set
<i>soap</i><tt>-&gt;</tt><i>error</i> when an error occurred. The callback should return
NULL (and not set <i>soap</i><tt>-&gt;</tt><i>error</i>) when this particular MTOM/MIME
attachment is not to be streamed.
</td></tr>
<tr><td align="left"><i>size_t (*soap.fmimeread)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>char</b>&nbsp;*buf, size_t len)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time MTOM/MIME attachment sender to read more data from a
(binary) data source for streaming into the output stream.  The <i>handle</i>
contains the value returned by the <i>fmimereadopen</i> callback.  The <i>buf</i>
argument is the buffer of length <i>len</i> into which a chunk of data should be
stored.  The actual amount of data stored in the buffer may be less than
<i>len</i> and this amount should be returned by the application.  A return value
of 0 indicates an error (the callback may set <i>soap</i><tt>-&gt;</tt><i>errnum</i> to errno).
The <i>__size</i> field of the attachment
struct/class should have been set by the application prior to the serialization
of the content.  The value of <i>__size</i> indicates the total size of the
content to be transmitted.  When the <i>__size</i> is zero then MTOM/MIME chunked
transfers can be used under certain circumstances to stream content without
prior determination of attachment size, see Section&nbsp;<a href="#sec:mimechunking">16.5</a> below.
</td></tr>
<tr><td align="left"><i><b>void</b>(*soap.fmimereadclose)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time MTOM/MIME attachment sender at the end of the
streaming process to close the data source.  The <i>handle</i> contains the
value returned by the <i>fmimereadopen</i> callback.  The <i>fmimewriteclose</i>
callback is called after successfully transmitting the data or when an error
occurred.
</td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;*(*soap.fmimewriteopen)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*description, <b>enum</b>&nbsp;soap_mime_encoding encoding)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time MTOM/MIME attachment receiver to start writing an
inbound MTOM/MIME attachment to an application's data store. The content is streamed
into an application data store through multiple <i>fmimewrite</i> calls from the
gSOAP attachment receiver.  The <i>handle</i> argument is normally NULL, unless <i>soap_get_mime_attachment</i> is used that passes the handle to the callback, see Section&nbsp;<a href="#sec:MTOMpoststreaming">16.4</a>. The <i>id</i>, <i>type</i>, and <i>description</i>
arguments are the MTOM/MIME id, type, and description respectively. The <i>encoding</i> enumeration value indicates the MIME content transfer encoding, which is one of
  <i>SOAP_MIME_NONE</i>,
  <i>SOAP_MIME_7BIT</i>,
  <i>SOAP_MIME_8BIT</i>,
  <i>SOAP_MIME_BINARY</i>,
  <i>SOAP_MIME_QUOTED_PRINTABLE</i>,
  <i>SOAP_MIME_BASE64</i>,
  <i>SOAP_MIME_IETF_TOKEN</i>,
  <i>SOAP_MIME_X_TOKEN</i>.
Content decoding may have to be considered by the application based on this value.
The callback should
return a non-NULL handle which is passed to the <i>fmimewrite</i> and
<i>fmimewriteclose</i> callbacks. The <i>__ptr</i> field of the attachment
struct/class is set to the value of this handle. The <i>__size</i> field is set
to the total size of the attachment after receiving the entire content. The size
is unknown in advance because MTOM/MIME attachments may be chunked.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fmimewrite)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>const</b>&nbsp;<b>char</b>&nbsp;*buf, size_t len)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time MTOM/MIME attachment receiver to write part of
an inbound MTOM/MIME attachment to an application's data store.
The <i>handle</i>
contains the value returned by the <i>fmimewriteopen</i> callback.  The <i>buf</i>
argument contains the data of length <i>len</i>.
The callback should return a gSOAP error code (e.g.&nbsp;<i>SOAP_OK</i> when no error occurred).
</td></tr>
<tr><td align="left"><i><b>void</b>(*soap.fmimewriteclose)(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle)</i> </td></tr>
<tr><td align="left">Called by the gSOAP run-time MTOM/MIME attachment receiver at the end of the
streaming process to close the data store.  The <i>fmimewriteclose</i> callback
is called after successfully receiving the data or when an error occurred.  The
<i>handle</i> contains the value returned by the <i>fmimewriteopen</i> callback.
</td></tr></table>

</td></tr></table><br></span>
In addition, a <i><b>void</b>*user</i> field in the <i><b>struct</b>&nbsp;soap</i> data structure
is available to pass user-defined data to the callbacks.  This way, you can set
<i>soap.user</i> to point to application data that the callbacks need such as a
file name for example.

<div class="p"><!----></div>
The following example illustrates the client-side initialization of an image
attachment struct to stream a file into a MTOM attachment without HTTP chunking (HTTP streaming chunked MTOM transfer is presented in Section&nbsp;<a href="#sec:mimechunking">16.5</a>):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;xsd__base64Binary image; <br />
&nbsp;&nbsp;&nbsp;FILE *fd; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;stat sb; <br />
&nbsp;&nbsp;&nbsp;soap_init1(&amp;soap, SOAP_ENC_MTOM); // mandatory to enable MTOM <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!fstat(fileno(fd), &amp;sb) &amp;&amp; sb.st_size  &gt;  0) <br />
&nbsp;&nbsp;&nbsp;{ // because we can get the length of the file, we can stream it without chunking <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.fmimereadopen = mime_read_open; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.fmimereadclose = mime_read_close; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.fmimeread = mime_read; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;image.__ptr = (<b>unsigned</b>&nbsp;<b>char</b>*)fd; // must set to non-NULL (this is our fd handle which we need in the callbacks) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;image.__size = sb.st_size; // must set size <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;{ // don't know the size, so buffer it <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;size_t i; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;c; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;image.__ptr = (<b>unsigned</b>&nbsp;<b>char</b>*)soap_malloc(&amp;soap, MAX_FILE_SIZE); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  MAX_FILE_SIZE; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;((c = fgetc(fd)) == EOF) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;image.__ptr[i] = c; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fclose(fd); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;image.__size = i; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;image.type = "image/jpeg"; // MIME type <br />
&nbsp;&nbsp;&nbsp;image.options = "This is my picture"; // description of object <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__method(&amp;soap, ...); <br />
&nbsp;&nbsp;&nbsp;... <br />
} <br />
<b>void</b>&nbsp;*mime_read_open(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*description) <br />
{ <b>return</b>&nbsp;handle; <br />
} <br />
<b>void</b>&nbsp;mime_read_close(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle) <br />
{ fclose((FILE*)handle); <br />
} <br />
size_t mime_read(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>char</b>&nbsp;*buf, size_t len) <br />
{ <b>return</b>&nbsp;fread(buf, 1, len, (FILE*)handle); <br />
}
</td></tr></table><br></i>
The following example illustrates the streaming of a MTOM/MIME attachment into a file by a client:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap.fmimewriteopen = mime_write_open; <br />
&nbsp;&nbsp;&nbsp;soap.fmimewriteclose = mime_write_close; <br />
&nbsp;&nbsp;&nbsp;soap.fmimewrite = mime_write; <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__method(&amp;soap, ...); <br />
&nbsp;&nbsp;&nbsp;... <br />
} <br />
<b>void</b>&nbsp;*mime_write_open(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*description, <b>enum</b>&nbsp;soap_mime_encoding encoding) <br />
{ <br />
&nbsp;&nbsp;&nbsp;FILE *handle = fopen("somefile", "wb"); <br />
&nbsp;&nbsp;&nbsp;// We ignore the MIME content transfer encoding here, but should check <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!handle) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>error = SOAP_EOF; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>errnum = errno; // get reason <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;(<b>void</b>*)handle; <br />
} <br />
<b>void</b>&nbsp;mime_write_close(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle) <br />
{ fclose((FILE*)handle); <br />
} <br />
<b>int</b>&nbsp;mime_write(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>const</b>&nbsp;<b>char</b>&nbsp;*buf, size_t len) <br />
{ <br />
&nbsp;&nbsp;&nbsp;size_t nwritten; <br />
&nbsp;&nbsp;&nbsp;<b>while</b>&nbsp;(len) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;nwritten = fwrite(buf, 1, len, (FILE*)handle); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!nwritten) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>errnum = errno; // get reason <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_EOF; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;len -= nwritten; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buf += nwritten; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
Note that compression can be used with MTOM/MIME to compress the entire message.
However, compression requires buffering to determine the HTTP content length
header, which cancels the benefits of streaming MTOM/MIME. To avoid this, you should
use chunked HTTP (with the output-mode <i>SOAP_IO_CHUNK</i> flag) with
compression and streaming MTOM/MIME. At the server side, when you set
<i>SOAP_IO_CHUNK</i> before calling <i>soap_serve</i>, gSOAP will
automatically revert to buffering (<i>SOAP_IO_STORE</i> flag is set).  You can
check this flag with <i>(soap-&#62;omode &amp; SOAP_IO) == SOAP_IO_CHUNK</i> to see
if the client accepts chunking. More information about streaming chunked MTOM/MIME
can be found in Section&nbsp;<a href="#sec:mimechunking">16.5</a>.

<div class="p"><!----></div>
Note that the example above for <i>mime_read</i> uses a handle that points to the open file
<i>FILE*</i>.
The simple example above is not recommended when the
platform imposes a limit on the number of open file descriptors.
You can use the handle to pass along more information than just
the file descriptor. So for example, when the number of open file descriptors
is limited on your platform, you should let the handle point to a structure
with file-related information. The C++ example below illustrates this:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
file.xop__Include = soap_new__xop__Include(soap); <br />
file.xop__Include-&#62;id = NULL; <br />
file.xop__Include-&#62;type = type; <br />
file.xop__Include-&#62;options = NULL; <br />
<br />
file.xmime5__contentType = type; <br />
file.filename = filename; <br />
<br />
// The object holding all information to read data <br />
FileStreamIn *ins = <b>new</b>&nbsp;FileStreamIn(errorhandler); <br />
ins<tt>-&gt;</tt>setFilePath(path); <br />
ins<tt>-&gt;</tt>setFileName(filename); <br />
<br />
file.xop__Include<tt>-&gt;</tt>__size = size; <br />
file.xop__Include<tt>-&gt;</tt>__ptr = (<b>unsigned</b>&nbsp;<b>char</b>*)ins;
</td></tr></table><br></i>
To read the MTOM data for transmission:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>void</b>&nbsp;*mime_read_open(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>const</b>&nbsp;<b>char</b>&nbsp;*id, <b>const</b>&nbsp;<b>char</b>&nbsp;*type, <b>const</b>&nbsp;<b>char</b>&nbsp;*description) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!handle) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;NULL; <br />
&nbsp;&nbsp;&nbsp;FileStreamIn *ins = (FileStreamIn*)handle; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!ins<tt>-&gt;</tt>open()) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>error = SOAP_ERR; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;NULL; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;handle; <br />
} <br />
<b>void</b>&nbsp;mime_read_close(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!handle) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>; <br />
&nbsp;&nbsp;&nbsp;FileStreamIn *ins = (FileStreamIn*)handle; <br />
&nbsp;&nbsp;&nbsp;<b>delete</b>&nbsp;ins; <br />
} <br />
size_t mime_read(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle, <b>char</b>&nbsp;*buf, size_t len) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!handle) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
&nbsp;&nbsp;&nbsp;FileStreamIn *ins = (FileStreamIn*)handle; <br />
&nbsp;&nbsp;&nbsp;size_t nread = ins<tt>-&gt;</tt>read(buf, len); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(ins<tt>-&gt;</tt>streamError()) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>error = ins<tt>-&gt;</tt>streamError(); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;nread; <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
		     <h3><a name="tth_sEc16.4">
16.4</a>&nbsp;&nbsp;<font color="#0000FF">Redirecting Inbound MTOM/MIME Streams Based on SOAP Body Content</font></h3><a name="sec:MTOMpoststreaming">
</a>

<div class="p"><!----></div>
When it is preferable or required to redirect inbound MTOM/MIME attachment
streams based on SOAP message body content, where for example the names of the
resources are listed in the SOAP message body, an alternative mechanism must be
used. This mechanism can be used both at the client and server side.

<div class="p"><!----></div>
Because the routing of the streams is accomplished with explicit function
calls, this method should only be used when required and should not be
considered optional. That is, when you enable this method, you MUST check for
pending MTOM/MIME attachments and handle them appropriately. This is true even
when you don't expect MTOM/MIME attachments in the payload, because the peer
may trick you by sending attachments anyway and you should be prepared to
accept or reject them.

<div class="p"><!----></div>
The explicit MTOM/MIME streaming mechanism consists of three API functions:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function</b></font> </td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;soap_post_check_mime_attachments(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Enables post-message body inbound streaming MTOM/MIME attachments. The presence
of attachments must be explicitly checked using the function below.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap_check_mime_attachments(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Should be
called after a client-side call (e.g.&nbsp;<i>soap_call_ns__method</i>) to check
the presence of attachments. Returns 1 (true) when attachments are present. If
present, each attachment MUST be processed with the function below.
</td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap_multipart *soap_get_mime_attachment(<b>struct</b>&nbsp;soap *soap, <b>void</b>&nbsp;*handle)</i> </td></tr>
<tr><td align="left">Parses an attachment and invokes the MIME callbacks (when set). The <i>handle</i>
parameter is passed to <i>fmimewriteopen</i>. The handle may contain any data
that is extracted from the SOAP message body to guide the redirection of the
stream in the callbacks. The return value is a struct with a <i><b>char</b>&nbsp;*ptr</i>
field that contains the handle value returned by the <i>fmimewriteopen</i>
callback, and <i><b>char</b>&nbsp;*id</i>, <i><b>char</b>&nbsp;*type</i>, and <i><b>char</b>&nbsp;*description</i> fields with the optional MIME id, type, and description info.
</td></tr></table>

</td></tr></table><br></span>
Example client-side code in C:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap *soap = soap_new1(SOAP_ENC_MTOM); <br />
soap_post_check_mime_attachments(soap); <br />
... <br />
<b>if</b>&nbsp;(soap_call_ns__myMethod(soap, ...)) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(soap, stderr); // an error occurred <br />
<b>else</b><br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_check_mime_attachments(soap))
&nbsp;&nbsp;&nbsp;{ // attachments are present, channel is still open <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>do</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... // get data 'handle' from SOAP response and pass to callbacks <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... // set the fmime callbacks, if needed <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap_multipart *content = soap_get_mime_attachment(soap, (void*)handle); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf(<tt>"Received&nbsp;attachment&nbsp;with&nbsp;id=%s&nbsp;and&nbsp;type=%s\n"</tt>, content<tt>-&gt;</tt>id?content<tt>-&gt;</tt>id:"", content<tt>-&gt;</tt>type?content<tt>-&gt;</tt>type:""); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <b>while</b>&nbsp;(content); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap<tt>-&gt;</tt>error) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;} <br />
} <br />
... <br />
soap_destroy(soap); <br />
soap_end(soap); <br />
soap_free(soap); // detach and free context <br />
</td></tr></table><br></i>
The server-side service operations are implemented as usual, but with additional checks for MTOM/MIME attachments:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap *soap = soap_new1(SOAP_ENC_MTOM); <br />
soap_post_check_mime_attachments(soap); <br />
... <br />
soap_serve(soap); <br />
... <br />
<b>int</b>&nbsp;ns__myMethod(<b>struct</b>&nbsp;soap *soap, ...) <br />
{
&nbsp;&nbsp;&nbsp;... // server-side processing logic <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_check_mime_attachments(soap))
&nbsp;&nbsp;&nbsp;{ // attachments are present, channel is still open <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>do</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... // get data 'handle' from SOAP request and pass to callbacks <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... // set the fmime callbacks, if needed <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap_multipart *content = soap_get_mime_attachment(soap, (void*)handle); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf(<tt>"Received&nbsp;attachment&nbsp;with&nbsp;id=%s&nbsp;and&nbsp;type=%s\n"</tt>, content<tt>-&gt;</tt>id?content<tt>-&gt;</tt>id:"", content<tt>-&gt;</tt>type?content<tt>-&gt;</tt>type:""); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <b>while</b>&nbsp;(content); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap<tt>-&gt;</tt>error) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap<tt>-&gt;</tt>error; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;... // server-side processing logic <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
		     <h3><a name="tth_sEc16.5">
16.5</a>&nbsp;&nbsp;<font color="#0000FF">Streaming Chunked MTOM/MIME</font></h3><a name="sec:mimechunking">
</a>

<div class="p"><!----></div>
gSOAP automatically handles inbound chunked MTOM/MIME attachments (streaming or
non-streaming).  To transmit outbound MTOM/MIME attachments, the attachment sizes
MUST be determined in advance to calculate HTTP message length required to
stream MTOM/MIME over HTTP.  However, gSOAP also supports the transmission of
outbound chunked MTOM/MIME attachments without prior determination of MTOM/MIME
attachment sizes when certain conditions are met.  These conditions require
either non-HTTP transport (use the output-mode <i>SOAP_ENC_XML</i> flag), or
chunked HTTP transport (use the output-mode <i>SOAP_IO_CHUNK</i> flag).  You
can also use the <i>SOAP_IO_STORE</i> flag (which is also used automatically
with compression to determine the HTTP content length header) but that cancels
the benefits of streaming MTOM/MIME.

<div class="p"><!----></div>
To stream chunked MTOM/MIME, set the <i>__size</i> field of an attachment to
zero and enable HTTP chunking.  The MTOM/MIME <i>fmimeread</i> callback then
fetches data in chunks of any size between 1 and the value of the <i>len</i>
argument. The <i>fmimeread</i> callback should return 0 upon reaching the end of
the data stream.

<div class="p"><!----></div>
 <h2><a name="tth_sEc17">
17</a>&nbsp;&nbsp;<font color="#0000FF">XML Validation</font></h2><a name="sec:validation">
</a>

<div class="p"><!----></div>
The gSOAP XML parser applies basic rules to validate content. Constraints are not automatically verified unless explicitly
set using flags.  This helps to avoid interoperability problems with toolkits that do
not strictly enforce validation rules. In addition, we cannot always use strict
validation for SOAP RPC encoded messages, since SOAP RPC encoding adopts a very
loose serialization format.

<div class="p"><!----></div>
Validation constraints are enabled with the <i>SOAP_XML_STRICT</i> input mode
flag set, e.g.&nbsp;with <i>soap_set_imode(soap, SOAP_XML_STRICT)</i> or
<i>soap_new(SOAP_XML_STRICT)</i>, see Section&nbsp;<a href="#sec:flags">9.12</a> for the complete list
of flags. 

<div class="p"><!----></div>
	     <h3><a name="tth_sEc17.1">
17.1</a>&nbsp;&nbsp;<font color="#0000FF">Occurrence Constraints</font></h3>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc17.1.1">
17.1.1</a>&nbsp;&nbsp;<font color="#0000FF">Default Values</font></h4>

<div class="p"><!----></div>
Default values can be defined for optional elements and attributes, which means
that the default value will be used when the element or attribute value is not
present in the parsed XML. See also Section&nbsp;<a href="#sec:default">7.5.7</a> and  examples in
subsequent subsections below.

<div class="p"><!----></div>
Default values must be primitive types, integer, float, string, etc.
Default values can be specified for struct and class members, as shown in the example below:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__MyRecord <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;n = 5; // optional element with default value 5 <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name = "none"; // optional element with default value "none" <br />
&nbsp;&nbsp;&nbsp;@<b>enum</b>&nbsp;ns__color { RED, WHITE, BLUE } color = RED; // optional attribute with default value RED <br />
};
</td></tr></table><br></i>
Upon deserialization of absent data, these members will be set accordingly.
When classes are instantiated with <i>soap_new_ClassName</i> the instance will
be initialized with default values.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc17.1.2">
17.1.2</a>&nbsp;&nbsp;<font color="#0000FF">Elements with minOccurs and maxOccurs Restrictions</font></h4>

<div class="p"><!----></div>
To force the validation of minOccurs and maxOccurs contraints the <i>SOAP_XML_STRICT</i> input mode flag must be set.
The minOccurs and maxOccurs constraints are specified for fields of a struct and members of a class in a header file using the following syntax:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<u><span class="roman">Type</span></u> <u><span class="roman">fieldname</span></u> <font size="+1"><span class="roman">[</span></font><u><span class="roman">minOccurs</span></u><font size="+1"><span class="roman">[</span></font>:<u><span class="roman">maxOccurs</span></u><font size="+1"><span class="roman">]</span></font><font size="+1"><span class="roman">]</span></font> <font size="+1"><span class="roman">[</span></font>= <span class="roman">value</span><font size="+1"><span class="roman">]</span></font>
</td></tr></table><br></i>
The minOccurs and maxOccurs values must be integer literals. A default value can be provided. When minOccurs is not specified, it is assumed to be zero.

<div class="p"><!----></div>
For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__MyRecord <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;n = 5; // element with default value 5, minOccurs=0, maxOccurs=1<br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;m 1; // element with minOccurs=1 <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__size 0:10; // sequence &lt;item&#62; with minOccurs=0, maxOccurs=10<br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;*item; <br />
&nbsp;&nbsp;&nbsp;std::vector<tt>&lt;</tt>double<tt>&gt;</tt> nums 2; // sequence &lt;nums&#62; with minOccurs=2, maxOccurs=unbounded <br />
}; <br />
<b>struct</b>&nbsp;arrayOfint <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;*__ptr 1:100; // minOccurs=1, maxOccurs=100 <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;size; <br />
};
</td></tr></table><br></i>
Pointer-based struct fields and class members are allowed to be nillable when minOccurs is zero.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc17.1.3">
17.1.3</a>&nbsp;&nbsp;<font color="#0000FF">Required and Prohibited Attributes</font></h4>

<div class="p"><!----></div>
Similar to the minOccurs and maxOccurs annotations defined in the previous
section, attributes in a struct or class can be annotated with occurrence
constraints to make them optional (0), required (1), or prohibited (0:0).
Default values can be assigned to optional attributes.

<div class="p"><!----></div>
For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;ns__MyRecord <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>int</b>&nbsp;m 1; // required attribute (occurs at least once) <br />
&nbsp;&nbsp;&nbsp;@<b>int</b>&nbsp;n = 5; // optional attribute with default value 5<br />
&nbsp;&nbsp;&nbsp;@<b>int</b>&nbsp;o 0; // optional attribute (may or may not occur) <br />
&nbsp;&nbsp;&nbsp;@<b>int</b>&nbsp;p 0:0; // prohibited attribute <br />
};
</td></tr></table><br></i>
Remember to set the <i>SOAP_XML_STRICT</i> input mode flag to
enable the validation of attribute occurrence constraints.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc17.2">
17.2</a>&nbsp;&nbsp;<font color="#0000FF">Value Constraints</font></h3>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc17.2.1">
17.2.1</a>&nbsp;&nbsp;<font color="#0000FF">Data Length Restrictions</font></h4>

<div class="p"><!----></div>
A schema simpleType is defined with a <i><b>typedef</b></i> by taking a base primitive to defined a derived simpleType.  For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>int</b>&nbsp;time__seconds;
</td></tr></table><br></i>
This defines the following schema type in <i>time.xsd</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;simpleType name="seconds"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;restriction base="xsd:int"/&#62; <br />
&lt;/simpleType&#62;
</td></tr></table><br></tt>
A complexType with simpleContent is defined with a wrapper struct/class:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;time__date <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*__item; // some custom format date (restriction of string) <br />
&nbsp;&nbsp;&nbsp;@<b>enum</b>&nbsp;time__zone { EST, GMT, ... } zone; <br />
}
</td></tr></table><br></i>
This defines the following schema type in <i>time.xsd</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;complexType name="date"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;simpleContent&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;extension base="xsd:string"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/simpleContent&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;attribute name="zone" type="time:zone" use="optional"/&#62; <br />
&lt;/complexType&#62;
&lt;simpleType name="zone"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;restriction base="xsd:string"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;enumeration value="EST"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;enumeration value="GMT"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;&lt;/restriction&#62; <br />
&lt;/simpleType&#62;
</td></tr></table><br></tt>
Data value length constraints of simpleTypes and complexTypes with simpleContent are defined as follows.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*ns__string256 0:256; // simpleType restriction of string with max length 256 characters <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*ns__string10 10:10; // simpleType restriction of string with length of 10 characters <br />
<b>typedef</b>&nbsp;std::string *ns__string8 8; // simpleType restriction of string with at least 8 characters <br />
<b>struct</b>&nbsp;ns__data // simpleContent wrapper <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*__item :256; // simpleContent with at most 256 characters <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;*name 1; // required name attribute <br />
}; <br />
<b>struct</b>&nbsp;time__date // simpleContent wrapper <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*__item :100; <br />
&nbsp;&nbsp;&nbsp;@<b>enum</b>&nbsp;time__zone { EST, GMT, ... } zone = GMT; <br />
}
</td></tr></table><br></i>
Remember to set the <i>SOAP_XML_STRICT</i> input mode flag to
enable the validation of value length constraints.

<div class="p"><!----></div>
	      <h4><a name="tth_sEc17.2.2">
17.2.2</a>&nbsp;&nbsp;<font color="#0000FF">Value Range Restrictions</font></h4>

<div class="p"><!----></div>
Similar to data length constraints for string-based data, integer data value range
constraints of numeric simpleTypes and complexTypes with simpleContent are defined as
follows.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>int</b>&nbsp;ns__int10 0:10; // simpleType restriction of int 0..10 <br />
<b>typedef</b>&nbsp;LONG64 ns__long -1000000:1000000; // simpleType restriction of long64 -1000000..1000000 <br />
<b>typedef</b>&nbsp;<b>float</b>&nbsp;ns__float100 -100:100; // simpleType restriction of float -100..100 <br />
<b>struct</b>&nbsp;ns__data // simpleContent wrapper <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;__item 0:10; // simpleContent range 0..10 <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;*name 1; // required name attribute <br />
};
</td></tr></table><br></i>
Currently the value bounds must be integer valued. Therefore, floating point ranges are limited to integer bounds. This may change in future releases.

<div class="p"><!----></div>
	      <h4><a name="tth_sEc17.2.3">
17.2.3</a>&nbsp;&nbsp;<font color="#0000FF">Pattern Restrictions</font></h4>

<div class="p"><!----></div>
Patterns can be defined for simpleType content. However, patterns are currently not enforced in the validation process though possibly in future releases.

<div class="p"><!----></div>
To associate a pattern with a simpleType, you can define a simpleType with a <i><b>typedef</b></i> and a pattern string:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>int</b>&nbsp;time__second "[1-5]?[0-9] - 60";
</td></tr></table><br></i>
This defines the following schema type in <i>time.xsd</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;simpleType name="second"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;restriction base="xsd:int"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;pattern value="[1-5]?[0-9] - 60"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/restriction&#62; <br />
&lt;/simpleType&#62;
</td></tr></table><br></tt>
The pattern string MUST contain a valid regular expression.

<div class="p"><!----></div>
A special case for C format string patterns is introduced in gSOAP 2.8.18.
When <tt>xs:totalDigits</tt> and <tt>xs:fractionDigits</tt> are given in a XSD file,
then a C format string is produced to output floating point values with the
proper precision and scale. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;simpleType name="ratio"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;restriction base="xsd:float"&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;totalDigits value="5"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;fractionDigits value="2"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/restriction&#62; <br />
&lt;/simpleType&#62;
</td></tr></table><br></tt>
produces:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>float</b>&nbsp;time__ratio "%5.2f";
</td></tr></table><br></i>
The format string is used to format the output the floating point value in XML.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc17.3">
17.3</a>&nbsp;&nbsp;<font color="#0000FF">Element and Attribute Qualified/Unqualified Forms</font></h3>

<div class="p"><!----></div>
Struct, class, and union members represent elements and attributes that are
automatically qualified or unqualified depending on the schema element and
attribute default forms. The gSOAP engine always validates the prefixes of
elements and attributes. When a namespace mismatch occurs, the element or
attribute is not consumed which can lead to a validation error (unless the
complexType is extensible or when <i>SOAP_XML_STRICT</i> is turned off).

<div class="p"><!----></div>
See Section&nbsp;<a href="#sec:idtrans">10.3</a> for details on the
the struct/class/union member identifier translation rules.
Consider for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns schema elementForm: qualified <br />
//gsoap ns schema attributeForm: unqualified <br />
<b>struct</b>&nbsp;ns__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* name; <br />
};
</td></tr></table><br></i>
Here, the <i>ns__record</i> struct is serialized with qualified element <i>name</i> and unqualified attribute <i>type</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;ns:record type="..."&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;ns:name&#62;...&lt;/ns:name&#62; <br />
&lt;/ns:record&#62;
</td></tr></table><br></tt>
The "colon notation" for struct/class/union member field names is used to
override element and attribute qualified or unqualified forms. 
To override the form for individual members that represent elements and attributes, use a namespace prefix and colon with the member name:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns schema elementForm: qualified <br />
//gsoap ns schema attributeForm: unqualified <br />
<b>struct</b>&nbsp;ns__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* ns:type; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* :name; <br />
};
</td></tr></table><br></i>
where <i>name</i> is unqualified and <i>type</i> is qualified:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;ns:record ns:type="..."&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;name&#62;...&lt;/name&#62; <br />
&lt;/ns:record&#62;
</td></tr></table><br></tt>
The colon notation is a syntactic notation used only in the gSOAP header file
syntax, it is not translated to the C/C++ output.

<div class="p"><!----></div>
The colon notation does not avoid name clashes between members. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;x__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* name; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* x:name; <br />
};
</td></tr></table><br></i>
results in a redefinition error, since both members have the same name. To avoid name clashes, use a underscore suffix:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;x__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* name; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* x:name_; <br />
};
</td></tr></table><br></i>
Not that the namespace prefix convention can be used instead:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;x__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;@<b>char</b>&nbsp;* name; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* x__name; <br />
};
</td></tr></table><br></i>
which avoids the name clash. However, the resulting schema is different
since the last example generates a global <i>name</i> element definition that is
referenced by the local element.

<div class="p"><!----></div>
More specifically, the difference between the namespace prefix convention with double underscores
and colon notation is that the namespace prefix convention generates schema
element/attribute references to elements/attributes at the top level,
while the colon notation only affects the local element/attribute namespace
qualification by form overriding. This is best illustrated by an example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;x__record <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* :name; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* x:phone; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* x__fax; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;* y__zip; <br />
};
</td></tr></table><br></i>
which generates the following <i>x.xsd</i>schema:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;complexType name="record"&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;sequence&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="name" type="xsd:string" minOccurs="0" maxOccurs="1" nillable="true" form="unqualified"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element name="phone" type="xsd:string" minOccurs="0" maxOccurs="1" nillable="true" form="qualified"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element ref="x:fax" minOccurs="0" maxOccurs="1"/&#62; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;element ref="y:zip" minOccurs="0" maxOccurs="1"/&#62; <br />
&nbsp;&nbsp;&nbsp;&lt;/sequence&#62; <br />
  &lt;/complexType&#62; <br />
  &lt;element name="fax" type="xsd:string"/&#62;
</td></tr></table><br></tt>
and the <i>y.xsd</i> schema defines contains:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
&lt;element name="zip" type="xsd:string"/&#62;
</td></tr></table><br></tt>

<div class="p"><!----></div>
 <h2><a name="tth_sEc18">
18</a>&nbsp;&nbsp;<font color="#0000FF">SOAP/XML Over UDP</font></h2><a name="sec:udp">
</a>

<div class="p"><!----></div>
UDP is a simple, unreliable datagram protocol: UDP sockets are connectionless.
UDP address formats are identical to those used by TCP.  In particular UDP
provides a port identifier in addition to the normal Internet address format.
The UDP port space is separate from the TCP port space (i.e. a UDP port may not
be "connected" to a TCP port).  In addition broadcast packets may be sent
(assuming the underlying network supports this) by using a reserved "broadcast
address"; this address is network interface dependent.

<div class="p"><!----></div>
Client-side messages with SOAP-over-UDP endpoint URLs
(<i>soap.udp://...</i>) will be automatically transmitted as datagrams.
Server-side applications should set the <i>SOAP_IO_UDP</i> mode flag to
accept UDP requests, e.g. using <i>soap_init1</i> or <i>soap_set_mode</i>.

<div class="p"><!----></div>
The maximum message length for datagram packets is restricted by the buffer
size <i>SOAP_BUFLEN</i>, which is 65536 by default, unless
compiled with <i>WITH_LEAN</i> to support small-scale embedded systems.
For UDP transport <i>SOAP_BUFLEN</i> must not exceed the maximum UDP packet size
65536 (the size of datagram messages is constrained by the
UDP packet size 2<sup>16</sup>=65536 as per UDP standard). You can use gzip compression
to reduce the message size, but note that compressed SOAP-over-UDP is a
gSOAP-specific feature because it is not part of the SOAP-over-UDP
specification.

<div class="p"><!----></div>
The SOAP-over-UDP specification relies on WS-Addressing. The <i>wsa.h</i>
file in the <i>import</i> directory defines the WS-Addressing elements for
client and server applications.

<div class="p"><!----></div>
The gSOAP implementation conforms to the SOAP-over-UDP requirements:

<ul>
<li> SOAP-over-UDP server endpoint URL format: <i>soap.udp://host:port/path</i>
<div class="p"><!----></div>
</li>

<li> Support one-way message-exchange pattern (MEP) where a SOAP envelope is
  carried in a user datagram.
<div class="p"><!----></div>
</li>

<li> Support request-response message-exchange pattern (MEP) where SOAP envelopes
  are carried in user datagrams.
<div class="p"><!----></div>
</li>

<li> Support multicast transmission of SOAP envelopes carried in user datagrams.
<div class="p"><!----></div>
</li>

<li> Support both SOAP 1.1 and SOAP 1.2 envelopes.
<div class="p"><!----></div>
</li>
</ul>
The following additional features are also available, but are not supported by the SOAP-over-UDP specification:

<ul>
<li> Zlib/gzip message compression (compile <i>-DWITH_GZIP</i>).
<div class="p"><!----></div>
</li>

<li> SOAP with DIME attachments over UDP.
<div class="p"><!----></div>
</li>

<li> SOAP with MIME attachments (SwA) over UDP.
<div class="p"><!----></div>
</li>

<li> Support for IPv6 (compile <i>-DWITH_IPV6</i>)
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc18.1">
18.1</a>&nbsp;&nbsp;<font color="#0000FF">Using WS-Addressing with SOAP-over-UDP</font></h3><a name="sec:udp.h">
</a>

<div class="p"><!----></div>
A SOAP-over-UDP application MUST use WS-Addressing to control message delivery
as per SOAP-over-UDP specification.

<div class="p"><!----></div>
The <i>wsa.h</i> file in the <i>import</i> directory defines the
WS-Addressing elements.  To include the WS-Addressing elements in the SOAP
Header for messaging, a <i><b>struct</b>&nbsp;SOAP_ENV__Header</i> structure must be
defined in your header file with the appropriate WS-Addressing elements.
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "wsa.h" <br />
<b>struct</b>&nbsp;SOAP_ENV__Header <br />
{ <br />
&nbsp;&nbsp;&nbsp;mustUnderstand _wsa__MessageID  wsa__MessageID 0; <br />
&nbsp;&nbsp;&nbsp;mustUnderstand _wsa__RelatesTo *wsa__RelatesTo 0; <br />
&nbsp;&nbsp;&nbsp;mustUnderstand _wsa__From      *wsa__From      0; <br />
&nbsp;&nbsp;&nbsp;mustUnderstand _wsa__ReplyTo   *wsa__ReplyTo   0; <br />
&nbsp;&nbsp;&nbsp;mustUnderstand _wsa__FaultTo   *wsa__FaultTo   0; <br />
&nbsp;&nbsp;&nbsp;mustUnderstand _wsa__To         wsa__To        0; <br />
&nbsp;&nbsp;&nbsp;mustUnderstand _wsa__Action     wsa__Action    0; <br />
};
</td></tr></table><br></i>
We also included a <i>//gsoap wsa schema import</i> directive in the <i>wsa.h</i> file to enable the generation of WSDL
specifications that import (instead of includes) the WS-Addressing elements.
Note that the <i>//gsoapopt w</i> directive must not be present in your header file to enable WSDL generation.

<div class="p"><!----></div>
One-way SOAP-over-UDP messages (see Section&nbsp;<a href="#sec:oneway1">7.3</a>) should be
declared to include the <i>wsa:MessageID</i>, <i>wsa:To</i>, and <i>wsa:Action</i>
elements in the SOAP Header of the request message as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service method-header-part:          sendString wsa__MessageID <br />
//gsoap ns service method-header-part:          sendString wsa__To <br />
//gsoap ns service method-header-part:          sendString wsa__Action <br />
<b>int</b>&nbsp;ns__sendString(<b>char</b>&nbsp;*str, <b>void</b>);
</td></tr></table><br></i>
Request-response SOAP-over-UDP messages should be declared to include the
<i>wsa:MessageID</i>, <i>wsa:To</i>, <i>wsa:Action</i>, and <i>wsa:ReplyTo</i>
elements in the SOAP Header of the request message, and the the
<i>wsa:MessageID</i>, <i>wsa:To</i>, <i>wsa:Action</i>, and <i>wsa:RelatesTo</i>
elements in the SOAP Header of the response message:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service method-header-part:          echoString wsa__MessageID <br />
//gsoap ns service method-header-part:          echoString wsa__To <br />
//gsoap ns service method-header-part:          echoString wsa__Action <br />
//gsoap ns service method-input-header-part:    sendString wsa__ReplyTo <br />
//gsoap ns service method-output-header-part:   echoString wsa__RelatesTo <br />
<b>int</b>&nbsp;ns__echoString(<b>char</b>&nbsp;*str, <b>char</b>&nbsp;**res);
</td></tr></table><br></i>
For the content requirements of these elements, please consult the
SOAP-over-UDP specification and/or read the next sections explaining
SOAP-over-UDP unicast, multicast, one-way, and request-response client and
server applications.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc18.2">
18.2</a>&nbsp;&nbsp;<font color="#0000FF">Client-side One-way Unicast</font></h3>

<div class="p"><!----></div>
This example assumes that the gSOAP header file includes the SOAP Header with
WS-Addressing elements and the <i>ns__sendString</i> function discussed in
Section&nbsp;<a href="#sec:udp.h">18.1</a>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
<b>struct</b>&nbsp;SOAP_ENV__Header header; // the SOAP Header <br />
soap_init(&amp;soap); <br />
soap.send_timeout = 1; // 1s timeout <br />
soap_default_SOAP_ENV__Header(&amp;soap, &amp;header); // init SOAP Header <br />
header.wsa__MessageID = "<i>message ID</i>"; <br />
header.wsa__To = "<i>server URL</i>"; <br />
header.wsa__Action = "<i>server action</i>"; <br />
soap.header = &amp;header; // bind the SOAP Header for transport <br />
// Send the message over UDP: <br />
<b>if</b>&nbsp;(soap_send_ns__echoString(&amp;soap, "soap.udp://...", NULL, "hello world!")) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // report error <br />
soap_end(&amp;soap); // cleanup <br />
soap_destroy(&amp;soap); // cleanup <br />
soap_done(&amp;soap); // close connection (should not use soap struct after this)
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc18.3">
18.3</a>&nbsp;&nbsp;<font color="#0000FF">Client-side One-way Multicast</font></h3>

<div class="p"><!----></div>
This example is similar to the one-way unicast example discussed above, but
uses a broadcast address and the <i>SO_BROADCAST</i> socket option:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
<b>struct</b>&nbsp;SOAP_ENV__Header header; // the SOAP Header <br />
in_addr_t addr = inet_addr("1.2.3.4"); // optional <br />
soap_init(&amp;soap); <br />
soap.send_timeout = 1; // 1s timeout <br />
soap.connect_flags = SO_BROADCAST; // required for broadcast <br />
soap.ipv4_multicast_if = &amp;addr; // optional for IPv4: see setsockopt IPPROTO_IP IP_MULTICAST_IF <br />
soap.ipv6_multicast_if = addr; // optional for IPv6: multicast sin6_scope_id <br />
soap.ipv4_multicast_ttl = 1; // optional, see setsockopt IPPROTO_IP, IP_MULTICAST_TTL <br />
soap_default_SOAP_ENV__Header(&amp;soap, &amp;header); // init SOAP Header <br />
header.wsa__MessageID = "<i>message ID</i>"; <br />
header.wsa__To = "<i>server URL</i>"; <br />
header.wsa__Action = "<i>server action</i>"; <br />
soap.header = &amp;header; // bind the SOAP Header for transport <br />
// Send the message over UDP to a broadcast address: <br />
<b>if</b>&nbsp;(soap_send_ns__echoString(&amp;soap, "soap.udp://...", NULL, "hello world!")) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // report error <br />
soap_destroy(&amp;soap); // cleanup <br />
soap_end(&amp;soap); // cleanup <br />
soap_done(&amp;soap); // close connection (should not use soap struct after this)
</td></tr></table><br></i>

<div class="p"><!----></div>
Please refer to the socket options for IPPROTO_IP IP_MULTICAST_IF to specify
the default interface for multicast datagrams to be sent from. This
is a <i><b>struct</b>&nbsp;in_addr</i> (<i>in_addr_t</i> for <i>sin6_scope_id</i>)
interface value. Otherwise, the default interface set by the system
administrator will be used (if any).

<div class="p"><!----></div>
Please refer to the socket options for IPPROTO_IP IP_MULTICAST_TTL to limit
the lifetime of the packet. Multicast datagrams are sent with a default value
of 1, to prevent them to be forwarded beyond the local network. This parameter
can be set between 1 to 255.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc18.4">
18.4</a>&nbsp;&nbsp;<font color="#0000FF">Client-side Request-Response Unicast</font></h3>

<div class="p"><!----></div>
This example assumes that the gSOAP header file includes the SOAP Header with
WS-Addressing elements and the <i>ns__echoString</i> function discussed in
Section&nbsp;<a href="#sec:udp.h">18.1</a>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
<b>struct</b>&nbsp;SOAP_ENV__Header header; // the SOAP Header <br />
<b>struct</b>&nbsp;wsa__EndpointReferenceType replyTo; // (anonymous) reply address <br />
<b>char</b>&nbsp;*res; // server response <br />
soap_init(&amp;soap); <br />
soap.send_timeout = 1; // 1s timeout <br />
soap.recv_timeout = 1; // 1s timeout <br />
soap_default_SOAP_ENV__Header(&amp;soap, &amp;header); // init SOAP Header <br />
soap_default_wsa__EndpointReferenceType(&amp;soap, &amp;replyTo); // init reply address <br />
replyTo.Address = "http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous"; <br />
header.wsa__MessageID = "<i>message ID</i>"; <br />
header.wsa__To = "<i>server URL</i>"; <br />
header.wsa__Action = "<i>server action</i>"; <br />
header.wsa__ReplyTo = &amp;replyTo; <br />
soap.header = &amp;header; // bind the SOAP Header for transport <br />
// Send and receive messages over UDP: <br />
<b>if</b>&nbsp;(soap_call_ns__echoString(&amp;soap, "soap.udp://...", NULL, "hello world!", &amp;res)) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap.error == SOAP_EOF &amp;&amp; soap.errnum == 0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// Timeout: no response from server (message already delivered?) <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
} <br />
<b>else</b><br />
&nbsp;&nbsp;&nbsp;// UDP server response is stored in 'res' <br />
// check SOAP header received, if applicable <br />
check_header(&amp;soap.header); <br />
soap_destroy(&amp;soap); // cleanup <br />
soap_end(&amp;soap); // cleanup <br />
soap_done(&amp;soap); // close connection (should not use soap struct after this)
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc18.5">
18.5</a>&nbsp;&nbsp;<font color="#0000FF">Client-side Request-Response Multicast</font></h3>

<div class="p"><!----></div>
This example is similar to the request-response unicast example discussed
above, but uses a broadcast address and the <i>SO_BROADCAST</i> socket option.
Because we expect to receive multiple responses, we also need to use separate
request-response messages to send one request and consume multiple responses.
In this example we defined a <i>bcastString</i> request and a
<i>bcastStringResponse</i> response message, which are essentially declared as
one-way messages in the header file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service method-header-part:          bcastString wsa__MessageID <br />
//gsoap ns service method-header-part:          bcastString wsa__To <br />
//gsoap ns service method-header-part:          bcastString wsa__Action <br />
//gsoap ns service method-header-part:          bcastString wsa__ReplyTo <br />
<b>int</b>&nbsp;ns__bcastString(<b>char</b>&nbsp;*str, <b>void</b>); <br />
//gsoap ns service method-header-part:          bcastStringResponse wsa__MessageID <br />
//gsoap ns service method-header-part:          bcastStringResponse wsa__To <br />
//gsoap ns service method-header-part:          bcastStringResponse wsa__Action <br />
//gsoap ns service method-header-part:          bcastStringResponse wsa__RelatesTo <br />
<b>int</b>&nbsp;ns__bcastStringResponse(<b>char</b>&nbsp;*res, <b>void</b>);
</td></tr></table><br></i>
To obtain response one-way operations, use the wsdl2h <i>-b</i> option.

<div class="p"><!----></div>
The client code includes a loop to receive response messages until a timeout occurs:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
<b>struct</b>&nbsp;SOAP_ENV__Header header; <br />
<b>struct</b>&nbsp;wsa__EndpointReferenceType replyTo; <br />
<b>char</b>&nbsp;*res; <br />
soap_init(&amp;soap); <br />
soap.connect_flags = SO_BROADCAST; <br />
soap.send_timeout = 1; // 1s timeout <br />
soap.recv_timeout = 1; // 1s timeout <br />
soap_default_SOAP_ENV__Header(&amp;soap, &amp;header); <br />
soap.header = &amp;header; <br />
soap_default_wsa__EndpointReferenceType(&amp;soap, &amp;replyTo); <br />
replyTo.Address = "http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous"; <br />
header.wsa__MessageID = "<i>message ID</i>"; <br />
header.wsa__To = "<i>server URL</i>"; <br />
header.wsa__Action = "<i>server action</i>"; <br />
header.wsa__ReplyTo = &amp;replyTo; <br />
<b>if</b>&nbsp;(soap_send_ns__bcastString(&amp;soap, "soap.udp://...", NULL, "hello world!")) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
<b>else</b><br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(;;) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_recv_ns__bcastStringResponse(&amp;soap, &amp;res)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// Got response 'res' from a server <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap.error == SOAP_EOF &amp;&amp; soap.errnum == 0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// Timeout: no more messages received <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
} <br />
soap_destroy(&amp;soap); // cleanup <br />
soap_end(&amp;soap); // cleanup <br />
soap_done(&amp;soap); // close connection (should not use soap struct after this)
</td></tr></table><br></i>
Note that a server for the <i>bcastString</i> does not need to use two-one way
messages.  Thus, multicast request-response message pattern can be declared and
implemented as request-response operations at the server side.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc18.6">
18.6</a>&nbsp;&nbsp;<font color="#0000FF">SOAP-over-UDP Server</font></h3><a name="sec:soapoverudp">
</a>

<div class="p"><!----></div>
The following example code illustrates a SOAP-over-UDP server for one-way <i>sendString</i> and request-response <i>echoString</i> messages.
This example assumes that the gSOAP header file includes the SOAP Header with
WS-Addressing elements and the <i>ns__echoString</i> function discussed in
Section&nbsp;<a href="#sec:udp.h">18.1</a>.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;soap_init1(&amp;soap, SOAP_IO_UDP); // must set UDP flag <br />
&nbsp;&nbsp;&nbsp;// bind to host (NULL=current host) and port: <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_valid_socket(soap_bind(&amp;soap, host, port, 100))) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(;;) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_serve(&amp;soap)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // report the problem <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_destroy(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); // close connection <br />
} <br />
<b>int</b>&nbsp;ns__echoString(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*str, <b>char</b>&nbsp;**res) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap<tt>-&gt;</tt>header) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_sender_fault(soap, "No SOAP header", NULL); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__MessageID) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_sender_fault(soap, "No WS-Addressing MessageID", NULL); <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__RelatesTo = (<b>struct</b>&nbsp;wsa__Relationship*)soap_malloc(soap, <b>sizeof</b>(<b>struct</b>&nbsp;wsa__Relationship)); <br />
&nbsp;&nbsp;&nbsp;soap_default_wsa__Relationship(soap, soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__RelatesTo); <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__RelatesTo<tt>-&gt;</tt>__item = soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__MessageID; <br />
&nbsp;&nbsp;&nbsp;// must check for duplicate messages <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(check_received(soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__MessageID)) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// Request message already received <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_STOP; // don't return response <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__ReplyTo &#124;&#124; !soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__ReplyTo<tt>-&gt;</tt>Address) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_sender_fault(soap, "No WS-Addressing ReplyTo address", NULL); <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__To = soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__ReplyTo<tt>-&gt;</tt>Address; <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__MessageID = soap_strdup(soap, soap_int2s(soap, id_count++)) ; <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__Action = "http://genivia.com/udp/echoStringResponse"; <br />
&nbsp;&nbsp;&nbsp;*res = str; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
<b>int</b>&nbsp;ns__sendString(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*str) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap<tt>-&gt;</tt>header) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_STOP; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__MessageID) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_STOP; <br />
&nbsp;&nbsp;&nbsp;// must check for duplicate messages <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(check_received(soap<tt>-&gt;</tt>header<tt>-&gt;</tt>wsa__MessageID)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_STOP; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
<b>int</b>&nbsp;ns__sendStringResponse(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*res) <br />
{ <b>return</b>&nbsp;SOAP_NO_METHOD; } // we don't expect to serve this message
</td></tr></table><br></i>
The server binds to a host and port and accepts messages in a tight sequential
loop.  Because UDP does not have the equivalent of an accept the messages
cannot be dispatched to threads, the <i>soap_serve</i> waits for a message and
immediately accepts it. You can use a receive timeout to make <i>soap_serve</i>
non-blocking.

<div class="p"><!----></div>
To obtain response one-way operations from a WSDL, use the wsdl2h <i>-b</i> option. This produces additional one-way operations to support asynchronous handling of response messages in the same way requests are handled.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc18.7">
18.7</a>&nbsp;&nbsp;<font color="#0000FF">SOAP-over-UDP Multicast Receiving Server</font></h3>

<div class="p"><!----></div>
For UDP multicast support, follow the suggestions in
Section&nbsp;<a href="#sec:soapoverudp">18.6</a> and change the initialization parts of the code
to enable UDP multicast port binding by to telliing the kernel which multicast
groups you are interested in:

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;ip_mreq mcast; <br />
&nbsp;&nbsp;&nbsp;soap_init1(&amp;soap, SOAP_IO_UDP);
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_valid_socket(soap_bind(&amp;soap, host, port, 100))) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;mcast.imr_multiaddr.s_addr = inet_addr("<tt>put IP multicast address of group here</tt>"); <br />
&nbsp;&nbsp;&nbsp;mcast.imr_interface.s_addr = htonl(INADDR_ANY); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(setsockopt(soap.master, IPPROTO_IP, IP_ADD_MEMBERSHIP, &amp;mcast, sizeof(mcast))&lt;0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... error ...
</td></tr></table><br></i>

<div class="p"><!----></div>
 <h2><a name="tth_sEc19">
19</a>&nbsp;&nbsp;<font color="#0000FF">Advanced Features</font></h2><a name="sec:advanced">
</a>

<div class="p"><!----></div>
		     <h3><a name="tth_sEc19.1">
19.1</a>&nbsp;&nbsp;<font color="#0000FF">Internationalization</font></h3>

<div class="p"><!----></div>
gSOAP uses regular strings by default.  Regular strings cannot be used to hold
UCS characters outside of the character range [1,255].  gSOAP can handle
wide-character content in two ways. First, applications can utilize
wide-character strings (<i>wchar_t*</i>) instead of regular strings to store
wide-character content.  For example, the <tt>xsd:string</tt> string schema type
can be declared as a wide-character string and used subsequently:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;wchar_t *xsd__string; <br />
... <br />
<b>int</b>&nbsp;ns__myMethod(xsd__string input, xsd__string *output);
</td></tr></table><br></i>
Second, regular strings can be used to hold wide-character content in UTF-8
format.  This is accomplished with the <i>SOAP_C_UTFSTRING</i> flag (for both input/output mode), see Section&nbsp;<a href="#sec:flags">9.12</a>.
With this flag set, gSOAP will deserialize XML into
regular strings in UTF-8 format.  An application is responsible for filling
regular strings with UTF-8 content to ensure that strings can be correctly serialized XML.
Third, the <i>SOAP_C_MBSTRING</i> flag (for both input/output mode) can be used to activate multibyte character support. Multibyte support depends on the locale settings for dealing with extended natural language encodings.

<div class="p"><!----></div>
Both regular strings and wide-character strings can be used together within an application.
For example, the following header file declaration introduces two string schema types:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;wchar_t *xsd__string; <br />
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*xsd__string_; // trailing '_' avoids name clash <br />
... <br />
<b>int</b>&nbsp;ns__myMethod(xsd__string input, xsd__string_ *output);
</td></tr></table><br></i>
The <i>input</i> string parameter is a wide-character string and the <i>output</i> string
parameter is a regular string.  The regular string has UCS character content 
in the range [1,255] unless the
<i>SOAP_C_UTFSTRING</i> flag is set.  With this flag, the string has UTF-8
encoded content.

<div class="p"><!----></div>
Please consult the UTF-8 specification for details on the UTF-8 format.
Note that the ASCII character set [1-127] is a subset of UTF-8. Therefore, with the <i>SOAP_C_UTFSTRING</i> flag set, strings may hold ASCII character data and UTF-8 extensions.

<div class="p"><!----></div>
		     <h3><a name="tth_sEc19.2">
19.2</a>&nbsp;&nbsp;<font color="#0000FF">Customizing the WSDL and Namespace Mapping Table File Contents With gSOAP Directives</font></h3><a name="sec:directives">
</a>

<div class="p"><!----></div>
A header file can be augmented with directives for the gSOAP <i>soapcpp2</i> tool to automatically generate customized WSDL and namespace mapping tables contents. The WSDL and namespace mapping table files do not need to be modified by hand (Sections&nbsp;<a href="#sec:wsdl">7.2.9</a> and&nbsp;<a href="#sec:nstable">10.4</a>).
In addition, the sample SOAP/XML request and response files generated by the compiler are valid provided that XML Schema namespace
information is added to the header file with directives so that the gSOAP <i>soapcpp2</i> compiler can produce example SOAP/XML messages that are correctly namespace qualified.
These compiler directive are specified as <i>//</i>-comments.
(Note: blanks can be used anywhere in the directive, except between <i>//</i> and <i>gsoap</i>.)

<div class="p"><!----></div>
Three directives are currently supported that can be used to specify details associated with namespace prefixes used by the service operation
names in the header file.
To specify the name of a Web Service in the header file, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service name: <i>service-name</i>
</td></tr></table><br></i>
where <i>namespace-prefix</i> is a namespace prefix used by identifiers in the header file and <i>service-name</i> is the name
of a Web Service (only required to create new Web Services).
The name may be followed by text up to the end of the line which is incorporated into the WSDL service documentation. Alternatively, the service documentation can be provided with the directive below.

<div class="p"><!----></div>
To specify the name of the WSDL definitions in the header file, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service definitions: <i>definitions-name</i>
</td></tr></table><br></i>
where <i>namespace-prefix</i> is a namespace prefix used by identifiers in the header file and <i>definitions-name</i> is the name of the WSDL definitions. By default, the WSDL definitions name is the same as the service name.

<div class="p"><!----></div>
To specify the documentation of a Web Service in the header file, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service documentation: <i>text</i>
</td></tr></table><br></i>
where <i>namespace-prefix</i> is a namespace prefix used by identifiers in the header file and <i>text</i> is the documentation text up to the end of the line.
The text is incorporated into the WSDL service documentation.

<div class="p"><!----></div>
To specify the portType of a Web Service in the header file, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service portType: <i>portType-name</i>
</td></tr></table><br></i>
or just
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service type: <i>portType-name</i>
</td></tr></table><br></i>
or using WSDL 2.0 terms
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service interface: <i>portType-name</i>
</td></tr></table><br></i>
where <i>namespace-prefix</i> is a namespace prefix used by identifiers in the header file and <i>portType-name</i> is the portType name of the WSDL service portType.

<div class="p"><!----></div>
To specify the port name of a Web Service in the header file, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service portName: <i>port-name</i>
</td></tr></table><br></i>
where <i>namespace-prefix</i> is a namespace prefix used by identifiers in the header file and <i>port-name</i> is the name of the WSDL service port element. By default, the port name is the same as the service name.

<div class="p"><!----></div>
To specify the binding name of a Web Service in the header file, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service binding: <i>binding-name</i>
</td></tr></table><br></i>
where <i>namespace-prefix</i> is a namespace prefix used by identifiers in the header file and <i>binding-name</i> is the binding name of the WSDL service binding element. By default, the binding name is the same as the service name.

<div class="p"><!----></div>
To specify the binding's transport protocol of a Web Service in the header file, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service transport: <i>transport-URL</i>
</td></tr></table><br></i>
where <i>namespace-prefix</i> is a namespace prefix used by identifiers in the header file and <i>transport-URL</i> is the URL of the transport protocol such as <i>http://schemas.xmlsoap.org/soap/http</i> for HTTP. HTTP transport is assumed by default.

<div class="p"><!----></div>
To specify the location (or port endpoint) of a Web Service in the header file, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service location: <i>URL</i>
</td></tr></table><br></i>
or alternatively
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service endpoint: <i>URL</i>
</td></tr></table><br></i>
or
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service port: <i>URL</i>
</td></tr></table><br></i>
where <i>URL</i> is the location of the Web Service (only required to create new Web Services).
The <i>URL</i> specifies the path to the service executable (so <i><i>URL</i>/<i>service-executable</i></i>
is the actual location of the executable when declared).

<div class="p"><!----></div>
To specify the name of the executable of a Web Service in the header file, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service executable: <i>executable-name</i>
</td></tr></table><br></i>
where <i>executable-name</i> is the name of the executable of the Web Service.

<div class="p"><!----></div>
When doc/literal encoding is required for the entire service, the service encoding can be specified in the header file as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service encoding: literal
</td></tr></table><br></i>
or when the <tt>SOAP-ENV:encodingStyle</tt> attribute is different from the SOAP 1.1/1.2 encoding style:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service encoding: <i>encoding-style</i>
</td></tr></table><br></i>

<div class="p"><!----></div>
To specify the namespace URI of a Web Service in the header file, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service namespace: <i>namespace-URI</i>
</td></tr></table><br></i>
where <i>namespace-URI</i> is the URI associated with the namespace prefix.

<div class="p"><!----></div>
In addition, the schema namespace URI can be specified in the header file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema namespace: <i>namespace-URI</i>
</td></tr></table><br></i>
where <i>namespace-URI</i> is the schema URI associated with the namespace prefix.
If present, it defines the schema-part of the generated WSDL file and the URI in the namespace mapping table.
This declaration is useful when the service declares its own data types that need to be associated with a namespace.
Furthermore, the header file for client applications do not need the full service details and the specification of the schema
namespaces for namespace prefixes suffices.
In addition, a second namespace can be defined that is only used to match the namespaces of inbound XML:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema namespace2: <i>namespace-URI-pattern</i>
</td></tr></table><br></i>
If the first namespace does not match the inbound parsed XML, then the second
will be tried. This pattern may contain '*' multichar wildcards and '-' single
chard wildcards. This allows two or more namespace versions to be handled by
the same namespace prefix.

<div class="p"><!----></div>
The directive above specifies a new schema and the gSOAP <i>soapcpp2</i> compiler generates a schema files (.xsd) file for the schema.
An existing schema namespace URI can be imported with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema import: <i>namespace-URI</i>
</td></tr></table><br></i>
where <i>namespace-URI</i> is the schema URI associated with the namespace prefix.
gSOAP does not produce XML Schema files for imported schemas and imports the schema namespaces in the generated WSDL file.

<div class="p"><!----></div>
A schema namespace URI can be imported from a location with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema namespace: <i>namespace-URI</i> <br />
//gsoap <i>namespace-prefix</i> schema import: <i>schema-location</i>
</td></tr></table><br></i>

<div class="p"><!----></div>
The elementFormDefault and attributeFormDefault qualification of a schema can be defined with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema elementForm: qualified <br />
//gsoap <i>namespace-prefix</i> schema attributeForm: qualified
</td></tr></table><br></i>
or:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema elementForm: unqualified <br />
//gsoap <i>namespace-prefix</i> schema attributeForm: unqualified
</td></tr></table><br></i>
A shortcut to define the default qualification of elements and attributes of a schema:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema form: qualified
</td></tr></table><br></i>
or:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema form: unqualified
</td></tr></table><br></i>

<div class="p"><!----></div>
To include <tt>xsi:type</tt> attributes in the runtime XML element output for specific schemas, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema typed: yes
</td></tr></table><br></i>
Note that <i>soapcpp2 -t</i> enables <tt>xsi:type</tt> for all elements in the runtime XML output.

<div class="p"><!----></div>
To document a data type, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema type-documentation: <i>type-name</i> //<i>text</i>
</td></tr></table><br></i>
where <i>type-name</i> is the unqualified name of the data type and <i>text</i>
is a line of text terminated by a newline. Do not use any XML reserved
characters in <i>text</i> such as  &lt;  and  &gt; . Use well-formed XML and XHTML markup instead.
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns schema type-documentation: tdata stores <tt>&lt;a&nbsp;href="transaction.html"&gt;</tt>transaction<tt>&lt;/a&gt;</tt> data <br />
<b>class</b>&nbsp;ns__tdata <br />
{ ... }
</td></tr></table><br></i>

<div class="p"><!----></div>
To document a data type's fields and members, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> schema type-documentation: <i>type-name::field</i> //<i>text</i>
</td></tr></table><br></i>
where <i>type-name</i> is the unqualified name of the data type, <i>field</i> is a field, member, or enum name, and <i>text</i>
is a line of text terminated by a newline. Do not use any XML reserved
characters in <i>text</i> such as  &lt;  and  &gt; . Use well-formed XML and XHTML markup instead.
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns schema type-documentation: tdata::id the transaction number <br />
//gsoap ns schema type-documentation: tdata::state transaction state  <br />
//gsoap ns schema type-documentation: tstate::INIT initial state  <br />
//gsoap ns schema type-documentation: tstate::DONE final state  <br />
<b>class</b>&nbsp;ns__tdata <br />
{ @<b>int</b>&nbsp;id; <br />
&nbsp;&nbsp;&nbsp;<b>enum</b>&nbsp;ns__tstate { INIT, DONE } state; <br />
 &nbsp;&nbsp;&nbsp;... <br />
}
</td></tr></table><br></i>
The documentation form above can also be used to document SOAP/XML message
parts in the generated WSDL. For the type-name use the function name. For the field names, you can use the function name and/or the function argument names.

<div class="p"><!----></div>
To document a method, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-documentation: <i>method-name</i> //<i>text</i>
</td></tr></table><br></i>
where <i>method-name</i> is the unqualified name of the method and <i>text</i>
is a line of text terminated by a newline. Do not use any XML reserved
characters in <i>text</i> such as  &lt;  and  &gt; . Use well-formed XML and XHTML markup instead.
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service method-documentation: getQuote returns a <tt>&lt;i&gt;</tt>stock quote<tt>&lt;/i&gt;</tt> <br />
<b>int</b>&nbsp;ns__getQuote(<b>char</b>&nbsp;*symbol, <b>float</b>&nbsp;&amp;_result);
</td></tr></table><br></i>

<div class="p"><!----></div>
To specify the SOAP Action for a SOAP method, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-action: <i>method-name</i> <i>action</i>
</td></tr></table><br></i>
where <i>method-name</i> is the unqualified name of the method and <i>action</i>
is a string without spaces and blanks (the string can be quoted when preferred).
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service method-action: getQuote "" <br />
<b>int</b>&nbsp;ns__getQuote(<b>char</b>&nbsp;*symbol, <b>float</b>&nbsp;&amp;_result);
</td></tr></table><br></i>
Or, alternatively for the input action (part of the request):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service method-input-action: getQuote "" <br />
<b>int</b>&nbsp;ns__getQuote(<b>char</b>&nbsp;*symbol, <b>float</b>&nbsp;&amp;_result);
</td></tr></table><br></i>

<div class="p"><!----></div>
To specify the HTTP "location" of REST methods to a perform POST/GET/PUT action, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-action: <i>method-name</i> <i>action</i>
</td></tr></table><br></i>
where <i>method-name</i> is the unqualified name of the method and <i>action</i>
is a string without spaces and blanks (the string can be quoted when preferred).
This directive requires that the <i>protocol:</i> directive for this method is set to HTTP, POST, GET, or PUT.

<div class="p"><!----></div>
A response action and fault action are defined by:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-output-action: <i>method-name</i> <i>action</i>
//gsoap <i>namespace-prefix</i> service method-fault-action: <i>method-name</i> <i>action</i>
</td></tr></table><br></i>

<div class="p"><!----></div>
To override the SOAP or REST protocol of an operation (SOAP by default), use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-protocol: <i>method-name</i> <i>protocol</i>
</td></tr></table><br></i>
where <i>protocol</i> is one of
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><i>SOAP</i> </td><td align="left">default SOAP transport (supports 1.1 and 1.2) </td></tr>
<tr><td align="left"><i>SOAP1.1</i> </td><td align="left">SOAP 1.1 only </td></tr>
<tr><td align="left"><i>SOAP1.2</i> </td><td align="left">SOAP 1.2 only </td></tr>
<tr><td align="left"><i>SOAP-GET</i> </td><td align="left">one-way SOAP with HTTP GET </td></tr>
<tr><td align="left"><i>SOAP1.1-GET</i> </td><td align="left">one-way SOAP 1.1 with HTTP GET </td></tr>
<tr><td align="left"><i>SOAP1.2-GET</i> </td><td align="left">one-way SOAP 1.1 with HTTP GET </td></tr>
<tr><td align="left"><i>HTTP</i> </td><td align="left">REST HTTP (POST or one-way PUT) </td></tr>
<tr><td align="left"><i>POST</i> </td><td align="left">REST HTTP POST </td></tr>
<tr><td align="left"><i>GET</i> </td><td align="left">one-way REST HTTP GET </td></tr>
<tr><td align="left"><i>PUT</i> </td><td align="left">one-way REST HTTP PUT </td></tr>
<tr><td align="left"><i>DELETE</i> </td><td align="left">REST HTTP DELETE </td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
When document style is preferred for a particular service method, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-style: <i>method-name</i> document
</td></tr></table><br></i>

<div class="p"><!----></div>
When SOAP RPC encoding is required for a particular service method, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-encoding: <i>method-name</i> encoded
</td></tr></table><br></i>
When literal encoding is required for a particular service method, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-encoding: <i>method-name</i> literal
</td></tr></table><br></i>
or when the <tt>SOAP-ENV:encodingStyle</tt> attribute is different from the SOAP 1.1/1.2 encoding style, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-encoding: <i>method-name</i> <i>encoding-style</i>
</td></tr></table><br></i>

<div class="p"><!----></div>
When SOAP RPC encoding is required for a particular service method response when the request message is literal, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-response-encoding: <i>method-name</i> encoded
</td></tr></table><br></i>
When literal encoding is required for a particular service method response when the request message is encoded, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-response-encoding: <i>method-name</i> literal
</td></tr></table><br></i>
or when the <tt>SOAP-ENV:encodingStyle</tt> attribute is different from the SOAP 1.1/1.2 encoding style, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-response-encoding: <i>method-name</i> <i>encoding-style</i>
</td></tr></table><br></i>
Note that the <i>method-response-encoding</i> is set to the value of <i>method-encoding</i> by default.

<div class="p"><!----></div>
When header processing is required, each method declared in the WSDL should provide a binding to the parts of the header that may
appear as part of a method request message. Such a binding is given by:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-header-part: <i>method-name</i> <i>header-part</i>
</td></tr></table><br></i>
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;SOAP_ENV__Header <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*h__transaction; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;UserAuth *h__authentication; <br />
};
</td></tr></table><br></i>
Suppose method <i>ns__login</i> uses both header parts (at most), then this is declared as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service method-header-part: login h__transaction <br />
//gsoap ns service method-header-part: login h__authentication <br />
<b>int</b>&nbsp;ns__login(...);
</td></tr></table><br></i>
Suppose method <i>ns__search</i> uses only the first header part, then this is declared as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service method-header-part: search h__transaction <br />
int ns__search(...);
</td></tr></table><br></i>
Note that the method name and header part names MUST be namespace qualified.
The headers MUST be present in all operations that declared the header parts.

<div class="p"><!----></div>
To specify the header parts for the method input (method request message), use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-input-header-part: <i>method-name</i> <i>header-part</i>
</td></tr></table><br></i>
Similarly, to specify the header parts for the method output (method response message), use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-output-header-part: <i>method-name</i> <i>header-part</i>
</td></tr></table><br></i>
The declarations above only affect the WSDL.
For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;SOAP_ENV__Header <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*h__transaction; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;UserAuth *h__authentication; <br />
}; <br />
//gsoap ns service method-input-header-part: login h__authentication <br />
//gsoap ns service method-input-header-part: login h__transaction <br />
//gsoap ns service method-output-header-part: login h__transaction <br />
<b>int</b>&nbsp;ns__login(...);
</td></tr></table><br></i>
The headers MUST be present in all operations that declared the header parts.

<div class="p"><!----></div>
To specify MIME attachments for the method input and output (method request and response messages), use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-mime-type: <i>method-name</i> <i>mime-type</i>
</td></tr></table><br></i>
You can repeat this directive for all multipartRelated MIME attachments you want to associate with the method.

<div class="p"><!----></div>
To specify MIME attachments for the method input (method request message), use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-input-mime-type: <i>method-name</i> <i>mime-type</i>
</td></tr></table><br></i>
Similarly, to specify MIME attachments for the method output (method response message), use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap <i>namespace-prefix</i> service method-output-mime-type: <i>method-name</i> <i>mime-type</i>
</td></tr></table><br></i>
You can repeat these directives for all multipartRelated MIME attachments you want to associate with the method.

<div class="p"><!----></div>
	      <h4><a name="tth_sEc19.2.1">
19.2.1</a>&nbsp;&nbsp;<font color="#0000FF">Example</font></h4>

<div class="p"><!----></div>
The use of directives is best illustrated with an example. The example uses a
hypothetical stock quote service and exchange rate service, actual services 
such as these are available for free on the web.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns1 service namespace:	urn:GetQuote <br />
<b>int</b>&nbsp;ns1__getQuote(<b>char</b>&nbsp;*symbol, <b>float</b>&nbsp;&amp;result); <br />
 <br />
//gsoap ns2 service namespace:	urn:CurrencyExchange <br />
<b>int</b>&nbsp;ns2__getRate(<b>char</b>&nbsp;*country1, <b>char</b>&nbsp;*country2, <b>float</b>&nbsp;&amp;result); <br />
 <br />
//gsoap ns3 service name:	quotex <br />
//gsoap ns3 service style:	rpc <br />
//gsoap ns3 service encoding:	encoded <br />
//gsoap ns3 service port:	http://www.mydomain.com/quotex.cgi <br />
//gsoap ns3 service namespace:	urn:quotex <br />
<b>int</b>&nbsp;ns3__getQuote(<b>char</b>&nbsp;*symbol, <b>char</b>&nbsp;*country, <b>float</b>&nbsp;&amp;result);
</td></tr></table><br></i>
The <i>quotex.h</i> example is a new Web Service created by combining two existing Web Services:
a Stock Quote service and a Currency Exchange service.

<div class="p"><!----></div>
Namespace prefix <i>ns3</i> is used for the new <i>quotex</i> Web Service with namespace URI <i>urn:quotex</i>,
service name <i>quotex</i>, and endpoint port <i>http://www.mydomain.com/quotex.cgi</i>.

<div class="p"><!----></div>
Since the new Web Service invokes the <i>ns1__getQuote</i> and <i>ns2__getRate</i> service operations,
the service namespaces and other details such as style and encoding of these methods are given by directives.
After invoking the gSOAP <i>soapcpp2</i> tool on the <i>quotex.h</i> header file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 quotex.h</i>
</td></tr></table><br></span>
the WSDL of the new <i>quotex</i> Web Service is saved as <i>quotex.wsdl</i>.
Since the service name, endpoint port, and namespace URI
were provided in the header file, the generated WSDL file can be published
together with the compiled Web Service installed as a CGI application.

<div class="p"><!----></div>
The namespace mapping table for the <i>quotex.cpp</i> Web Service implementation
is saved as <i>quotex.nsmap</i>.  This file can be directly included in
<i>quotex.cpp</i> instead of specified by hand in the source of
<i>quotex.cpp</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "quotex.nsmap"
</td></tr></table><br></i>
The automatic generation and inclusion of the namespace mapping table requires
compiler directives for <b>all</b> namespace prefixes to associate each
namespace prefix with a namespace URI. Otherwise, namespace URIs have to be
manually added to the table (they appear as <i>http://tempuri.org</i>).

<div class="p"><!----></div>
		     <h3><a name="tth_sEc19.3">
19.3</a>&nbsp;&nbsp;<font color="#0000FF">Transient Data Types</font></h3><a name="sec:transient">
</a>

<div class="p"><!----></div>
There are situations when certain data types have to be ignored by gSOAP for
the compilation of (de)marshalling routines.  For example, in certain cases
only a few members of a class or struct need not be (de)serialized, or the base
class of a derived class should not be (de)serialized. Certain built-in classes
such as <i>ostream</i> cannot be (de)serialized.  Data parts that should be kept
invisible to gSOAP are called "transient".  Transient data types and
transient struct/class members are declared with the <i><b>extern</b></i> keyword or
are declared within <i>[</i> and <i>]</i> blocks in the header file.  The
<i><b>extern</b></i> keyword has a special meaning to the gSOAP <i>soapcpp2</i> compiler and won't
affect the generated codes.  The special <i>[</i> and <i>]</i> block construct
can be used with data type declarations and within <i><b>struct</b></i> and
<i><b>class</b></i> declarations. The use of <i><b>extern</b></i> or <i>[ ]</i> achieve the
same effect, but <i>[ ]</i> may be more convenient to encapsulate transient
types in a larger part of the header file. The use of <i><b>extern</b></i> with
<i><b>typedef</b></i> is reserved for the declaration of user-defined external
(de)serializers for data types, see Section&nbsp;<a href="#sec:extern">19.5</a>.

<div class="p"><!----></div>
First example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>extern</b>&nbsp;<b>class</b>&nbsp;ostream; // ostream can't be (de)serialized, but need to be declared to make it visible to gSOAP <br />
<b>class</b>&nbsp;ns__myClass <br />
{ ... <br />
&nbsp;&nbsp;&nbsp;<b>virtual</b>&nbsp;<b>void</b>&nbsp;print(ostream &amp;s) <b>const</b>; // need ostream here <br />
&nbsp;&nbsp;&nbsp;... <br />
};
</td></tr></table><br></i>
Second example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
[ <br />
&nbsp;&nbsp;&nbsp;<b>class</b>&nbsp;myBase // base class need not be (de)serialized <br />
&nbsp;&nbsp;&nbsp;{ ... }; <br />
] <br />
<b>class</b>&nbsp;ns__myDerived : myBase <br />
{ ... }; <br />
</td></tr></table><br></i>
Third example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
[ <b>typedef</b>&nbsp;<b>int</b>&nbsp;transientInt; ] <br />
<b>class</b>&nbsp;ns__myClass <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;a; // will be (de)serialized <br />
&nbsp;&nbsp;&nbsp;[ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;b; // transient field <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;s[256]; // transient field <br />
&nbsp;&nbsp;&nbsp;]  <br />
&nbsp;&nbsp;&nbsp;<b>extern</b>&nbsp;<b>float</b>&nbsp;d; // transient field <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*t; // will be (de)serialized <br />
&nbsp;&nbsp;&nbsp;transientInt *n; // transient field <br />
&nbsp;&nbsp;&nbsp;[ <br />
&nbsp;&nbsp;&nbsp;<b>virtual</b>&nbsp;<b>void</b>&nbsp;method(<b>char</b>&nbsp;buf[1024]); // does not create a <b>char</b>[1024] (de)serializer <br />
&nbsp;&nbsp;&nbsp;]  <br />
};
</td></tr></table><br></i>
In this example, <i><b>class</b>&nbsp;ns__myClass</i> has three transient fields:
<i>b</i>, <i>s</i>, and <i>n</i> which will not be (de)serialized in SOAP. Field
<i>n</i> is transient because the type is declared within a transient block.
Pointers, references, and arrays of transient types are transient.  The single
class method is encapsulated within <i>[</i> and <i>]</i> to prevent gSOAP from
creating (de)serializers for the <i><b>char</b>[1024]</i> type. gSOAP will generate
(de)serializers for all types that are not declared within a <i>[</i> and
<i>]</i> transient block.

<div class="p"><!----></div>
		     <h3><a name="tth_sEc19.4">
19.4</a>&nbsp;&nbsp;<font color="#0000FF">Serialization "as is" with Volatile Data Types</font></h3><a name="sec:volatile">
</a>

<div class="p"><!----></div>
Volatile-declared data types in gSOAP are assumed to be part of an
existing non-modifiable software package, such as a built-in library. It would
not make sense to redefine the data types in a gSOAP header file. In certain
cases it could also be problematic to have classes augmented with serializer
methods. When you need to (de)serialize such data types "as is", you must
declare them in a gSOAP header file and use the <i><b>volatile</b></i> qualifier.

<div class="p"><!----></div>
Consider for example <i><b>struct</b>&nbsp;tm</i>, declared in <i>time.h</i>. The structure may actually vary between platforms, but the tm structure includes at least the following fields:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>volatile</b>&nbsp;<b>struct</b>&nbsp;tm <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;tm_sec;         /* seconds (0 - 60) */ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;tm_min;         /* minutes (0 - 59) */ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;tm_hour;        /* hours (0 - 23) */ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;tm_mday;        /* day of month (1 - 31) */ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;tm_mon;         /* month of year (0 - 11) */ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;tm_year;        /* year - 1900 */ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;tm_wday;        /* day of week (Sunday = 0) */ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;tm_yday;        /* day of year (0 - 365) */ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;tm_isdst;       /* is summer time in effect? */ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*tm_zone;        /* abbreviation of timezone name */ <br />
&nbsp;&nbsp;&nbsp;<b>long</b>&nbsp;tm_gmtoff;      /* offset from UTC in seconds */ <br />
};
</td></tr></table><br></i>
Note that we qualified the structure <i><b>volatile</b></i> in the gSOAP header file to inform the gSOAP <i>soapcpp2</i> compiler that it should not attempt to redeclare it.
We can now readily serialize and deserialize the tm structure. The following program fragment serializes the local time stored in a tm structure to stdout:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap *soap = soap_new(); <br />
... <br />
time_t T = time(NULL); <br />
<b>struct</b>&nbsp;tm *t = localtime(&amp;T); <br />
<b>struct</b>&nbsp;soap *soap = soap_new(); <br />
soap_write_tm(soap, t); <br />
soap_destroy(soap); <br />
soap_end(soap); <br />
soap_free(soap); // detach and free context <br />
</td></tr></table><br></i>
It is also possible to serialize the tm fields as XML attributes using the
@qualifier, see Section&nbsp;<a href="#sec:attributes">11.6.7</a>.

<div class="p"><!----></div>
If you must produce a schema file, say <i>time.xsd</i>, that defines an XML
schema and namespace for the tm struct, you can add a <i><b>typedef</b></i>
declaration to the header file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>struct</b>&nbsp;tm time__struct_tm;
</td></tr></table><br></i>
We used the <i><b>typedef</b></i> name <i>time__struct_tm</i> rather than <i>time__
tm</i>, because a schema name clash will occur with the latter since taking off
the <i>time</i> prefix will result in the same name being used.

<div class="p"><!----></div>
Classes should be declared volatile to prevent modification of these classes by ithe gSOAP <i>soapcpp2</i> source code output.
Note that gSOAP adds serialization methods to classes to support polymorphism.  However,
this is a problem when you can't modify class declarations because they are
part of a non-modifiable software package.  The solution is to declare these
classes <i><b>volatile</b></i>, similar to the tm structure example illustrated above. 
You can also use a <i><b>typedef</b></i> to associate a schema with a class.

<div class="p"><!----></div>
		     <h3><a name="tth_sEc19.5">
19.5</a>&nbsp;&nbsp;<font color="#0000FF">How to Declare User-Defined Serializers and Deserializers</font></h3><a name="sec:extern">
</a>

<div class="p"><!----></div>
Users can declare their own (de)serializers for specific data types instead of relying on the gSOAP-generated (de)serializers.
To declare a external (de)serializer, declare a type with <i><b>extern</b>&nbsp;<b>typedef</b></i>. gSOAP will not generate the (de)serializers
for the type name that is declared. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>extern</b>&nbsp;<b>typedef</b>&nbsp;<b>char</b>&nbsp;*MyData; <br />
<b>struct</b>&nbsp;Sample <br />
{ <br />
&nbsp;&nbsp;&nbsp;MyData s; // use user-defined (de)serializer for this field <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*t; // use gSOAP (de)serializer for this field <br />
};
</td></tr></table><br></i>
The user is required to supply the following routines for each <i><b>extern</b>&nbsp;<b>typedef</b></i>'ed name <u>T</u>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>void</b>&nbsp;soap_serialize_<u><span class="roman">T</span></u>(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<u><span class="roman">T</span></u> *a) <br />
<b>void</b>&nbsp;soap_default_<u><span class="roman">T</span></u>(<b>struct</b>&nbsp;soap *soap, <u><span class="roman">T</span></u> *a) <br />
<b>void</b>&nbsp;soap_out_<u><span class="roman">T</span></u>(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*tag, <b>int</b>&nbsp;id, <b>const</b>&nbsp;<u><span class="roman">T</span></u> *a, <b>const</b>&nbsp;<b>char</b>&nbsp;*type) <br />
<u><span class="roman">T</span></u> *soap_in_<u><span class="roman">T</span></u>(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*tag, <u><span class="roman">T</span></u> *a, <b>const</b>&nbsp;<b>char</b>&nbsp;*type) 
</td></tr></table><br></i>
The function prototypes can be found in <i>soapH.h</i>.

<div class="p"><!----></div>
For example, the (de)serialization of <i>MyData</i> can be done with the following code:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>void</b>&nbsp;soap_serialize_MyData(<b>struct</b>&nbsp;soap *soap, MyData *<b>const</b>*a) <br />
{ } // no need to mark this node (for multi-ref and cycle detection) <br />
<b>void</b>&nbsp;soap_default_MyData(&amp;soap, MyData **a) <br />
{ *a = NULL } <br />
<b>void</b>&nbsp;soap_out_MyData(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*tag, <b>int</b>&nbsp;id, MyData *<b>const</b>*a, <b>const</b>&nbsp;<b>char</b>&nbsp;*type) <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_element_begin_out(soap, tag, id, type); // print XML beginning tag <br />
&nbsp;&nbsp;&nbsp;soap_send(soap, *a); // just print the string (no XML conversion) <br />
&nbsp;&nbsp;&nbsp;soap_element_end_out(soap, tag); // print XML ending tag <br />
} <br />
MyData **soap_in_MyData(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*tag, MyData **a, <b>const</b>&nbsp;<b>char</b>&nbsp;*type) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_element_begin_in(soap, tag)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;NULL; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!a) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;a = (MyData**)soap_malloc(soap, <b>sizeof</b>(MyData*)); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap<tt>-&gt;</tt>null) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*a = NULL; // xsi:nil element <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(*soap<tt>-&gt;</tt>type &amp;&amp; soap_match_tag(soap, soap<tt>-&gt;</tt>type, type)) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>error = SOAP_TYPE; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;NULL; // type mismatch <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(*soap<tt>-&gt;</tt>href) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;a = (MyData**)soap_id_forward(soap, soap<tt>-&gt;</tt>href, a, SOAP_MyData, <b>sizeof</b>(MyData*)) <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<b>if</b>&nbsp;(soap<tt>-&gt;</tt>body) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*s = soap_value(soap); // fill buffer <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*a = (<b>char</b>*)soap_malloc(soap, strlen(s)+1); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;strcpy(*a, s); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap<tt>-&gt;</tt>body &amp;&amp; soap_element_end_in(soap, tag)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;NULL; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;a;
</td></tr></table><br></i>
More information on custom (de)serialization will be provided in this document or in a separate document in the future.
The writing of the (de)serializer code requires the use of the low-level gSOAP API.

<div class="p"><!----></div>
		     <h3><a name="tth_sEc19.6">
19.6</a>&nbsp;&nbsp;<font color="#0000FF">How to Serialize Data Without Generating XSD Type Attributes</font></h3>

<div class="p"><!----></div>
gSOAP serializes data in XML with <tt>xsi:type</tt> attributes when the types are
declared with namespace prefixes to indicate the schema type of the data
contained in the elements. SOAP 1.1 and 1.2 requires <tt>xsi:type</tt> attributes
in the presence of polymorphic data or when the type of the data cannot be
deduced from the SOAP payload.  The namespace prefixes are associated with the
type names of <i><b>typedef</b></i>s (Section&nbsp;<a href="#sec:primitive">11.3</a>) for primitive data
types, <i><b>struct</b></i>/<i>class</i> names, and <i><b>enum</b></i> names.

<div class="p"><!----></div>
To prevent the output of these <tt>xsi:type</tt> attributes in the XML
serialization, you can simply use type declarations that do not include these
namespace prefixes.  That is, don't use the <i><b>typedef</b></i>s for primitive types
and use unqualified type names with <i><b>struct</b></i>s, <i><b>class</b></i>es, and
<i>enum</i>s.

<div class="p"><!----></div>
However, there are two issues.  Firstly, if you want to use a primitive schema
type that has no C/C++ counterpart, you must declare it as a <i><b>typedef</b></i>
name with a leading underscore, as in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>typedef</b>&nbsp;<b>char</b>&nbsp;*_xsd__date;
</td></tr></table><br></i>
This will produce the necessary <tt>xsd:date</tt> information in the WSDL output
by the gSOAP <i>soapcpp2</i> compiler.  But the XML serialization of this type at run time
won't include the <tt>xsi:type</tt> attribute.  Secondly, to include the proper
schema definitions in the WSDL produced by the gSOAP <i>soapcpp2</i> compiler, you should
use qualified <i><b>struct</b></i>, <i><b>class</b></i>, and <i><b>enum</b></i> names with a leading
underscore, as in: 
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;_ns__myStruct <br />
{ ... };
</td></tr></table><br></i>
This ensures that <i>myStruct</i> is associated with a schema, and therefore
included in the appropriate schema in the generated WSDL.  The leading
underscore prevents the XML serialization of <tt>xsi:type</tt> attributes for this
type in the SOAP/XML payload.

<div class="p"><!----></div>
		     <h3><a name="tth_sEc19.7">
19.7</a>&nbsp;&nbsp;<font color="#0000FF">Function Callbacks for Customized I/O and HTTP Handling</font></h3><a name="sec:callback">
</a>

<div class="p"><!----></div>
gSOAP provides five callback functions for customized I/O and HTTP handling:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Callback (function pointer)</b></font> </td></tr>
<tr><td align="left"><i>SOAP_SOCKET (*soap.fopen)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*endpoint, <b>const</b>&nbsp;<b>char</b>&nbsp;*host, <b>int</b>&nbsp;port)</i> </td></tr>
<tr><td align="left">Called from a client proxy to open a connection to a Web Service located at <i>endpoint</i>.
Input parameters <i>host</i> and <i>port</i> are micro-parsed from <i>endpoint</i>.
Should return a valid file descriptor, or <i>SOAP_INVALID_SOCKET</i> and <i>soap</i><tt>-&gt;</tt><i>error</i> set to an error code.
Built-in gSOAP function: <i>tcp_connect</i>
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fclose)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Called by client proxy <b>multiple times</b>, to close a socket connection before a new socket
connection is established and at the end of communications when the <i>SOAP_IO_KEEPALIVE</i> flag is not set
and <i>soap.keep_alive</i> &#8800; 0 (indicating that the other party supports keep alive).
Should return SOAP_OK, or a gSOAP error code.
Built-in gSOAP function: <i>tcp_disconnect</i>
</td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Callback (function pointer)</b></font> </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fget)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Called by the main server loop upon an HTTP GET request. The <i>SOAP_GET_METHOD</i> error is returned by default. This callback can be used to respond to HTTP GET methods with content, see Section&nbsp;<a href="#sec:get">19.10</a>.
Should return <i>SOAP_OK</i>, or a gSOAP error code.
Built-in gSOAP function: <i>http_get</i>
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fput)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Called by the main server loop upon an HTTP PUT request. The <i>SOAP_PUT_METHOD</i> error is returned by default. This callback can be used to respond to HTTP PUT.
Should return <i>SOAP_OK</i>, or a gSOAP error code.
Built-in gSOAP function: <i>http_put</i>
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fdel)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Called by the main server loop upon an HTTP DELETE request. The <i>SOAP_DELETE_METHOD</i> error is returned by default. This callback can be used to respond to HTTP DELETE methods.
Should return <i>SOAP_OK</i>, or a gSOAP error code.
Built-in gSOAP function: <i>http_del</i>
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fhead)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Called by the main server loop upon an HTTP HEAD request. The <i>SOAP_HEAD_METHOD</i> error is returned by default. This callback can be used to respond to HTTP HEAD methods.
Should return <i>SOAP_OK</i>, or a gSOAP error code.
Built-in gSOAP function: <i>http_get</i>
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fform)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Called by the main server loop when a user-defined <i>fparsehdr</i> callback returned <i>SOAP_FORM</i> to signal that the HTTP body must be processed by this form handler callback. The HTTP POST form data MUST be read, otherwise keep-alive messages will end up out of sync.
Should return <i>SOAP_OK</i> or a gSOAP error code.
Built-in gSOAP function: none.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fpost)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*endpoint, <b>const</b>&nbsp;<b>char</b>&nbsp;*host, <b>int</b>&nbsp;port, <b>const</b>&nbsp;<b>char</b>&nbsp;*path, <b>const</b>&nbsp;<b>char</b>&nbsp;*action, size_t count)</i> </td></tr>
<tr><td align="left">Called from a client proxy to generate the HTTP header to connect to <i>endpoint</i>.
Input parameters <i>host</i>, <i>port</i>, and <i>path</i> are micro-parsed from <i>endpoint</i>, <i>action</i> is the SOAP action,
and <i>count</i> is the length of the SOAP message or 0 when <i>SOAP_ENC_XML</i> is set or when <i>SOAP_IO_LENGTH</i> is reset.
Use function <i>soap_send(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*s)</i> to write the header contents.
Should return SOAP_OK, or a gSOAP error code.
Built-in gSOAP function: <i>http_post</i>.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fposthdr)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*key, <b>const</b>&nbsp;<b>char</b>&nbsp;*val)</i> </td></tr>
<tr><td align="left">Called by <i>http_post</i> and <i>http_response</i> (through the callbacks).
Emits HTTP <i>key</i>: <i>val</i> header entries.
Should return SOAP_OK, or a gSOAP error code.
Built-in gSOAP function: <i>http_post_header</i>.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fresponse)(<b>struct</b>&nbsp;soap *soap, <b>int</b>&nbsp;soap_error_code, size_t count)</i> </td></tr>
<tr><td align="left">Called from a service to generate the response HTTP header.
Input parameter <i>soap_error_code</i> is a gSOAP error code (see Section&nbsp;<a href="#sec:errcodes">10.2</a> and
<i>count</i> is the length of the SOAP message or 0 when <i>SOAP_ENC_XML</i> is set or when <i>SOAP_IO_LENGTH</i> is reset.
Use function <i>soap_send(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*s)</i> to write the header contents.
Should return SOAP_OK, or a gSOAP error code
Built-in gSOAP function: <i>http_response</i>
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fparse)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Called by client proxy and service to parse an HTTP header (if present).
When user-defined, this routine must at least skip the header.
Use function <i><b>int</b>&nbsp;soap_getline(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*buf, <b>int</b>&nbsp;len)</i> to read HTTP header lines into
a buffer <i>buf</i> of length <i>len</i> (returns empty line at end of HTTP header).
Should return <i>SOAP_OK</i>, or a gSOAP error code.
Built-in gSOAP function: <i>http_parse</i>
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fparsehdr)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*key, <b>const</b>&nbsp;<b>char</b>&nbsp;*val)</i> </td></tr>
<tr><td align="left">Called by <i>http_parse</i> (through the <i>fparse</i> callback).
Handles HTTP <i>key</i>: <i>val</i> header entries to set gSOAP's internals.
Should return <i>SOAP_OK</i>, <i>SOAP_STOP</i> (see <i>fstop</i>) or a gSOAP error code.
Built-in gSOAP function: <i>http_parse_header</i>
</td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Callback (function pointer)</b></font> </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fsend)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*s, size_t n)</i> </td></tr>
<tr><td align="left">Called for all send operations to emit contents of <i>s</i> of length <i>n</i>.
Should return SOAP_OK, or a gSOAP error code.
Built-in gSOAP function: <i>fsend</i>
</td></tr>
<tr><td align="left"><i>size_t (*soap.frecv)(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*s, size_t n)</i> </td></tr>
<tr><td align="left">Called for all receive operations to fill buffer <i>s</i> of maximum length <i>n</i>.
Should return the number of bytes read or 0 in case of an error, e.g.&nbsp;EOF.
Built-in gSOAP function: <i>frecv</i>
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fignore)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*tag)</i> </td></tr>
<tr><td align="left">Called when an unknown XML element was encountered on the input. The <i>tag</i> parameter is the offending XML element tag name.
Should return <i>SOAP_OK</i>, or a gSOAP error code such as <i>SOAP_TAG_MISMATCH</i> to throw an exception.
Built-in gSOAP function: none.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fconnect)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*endpoint, <b>const</b>&nbsp;<b>char</b>&nbsp;*host, <b>int</b>&nbsp;port)</i> </td></tr>
<tr><td align="left">When non-NULL, this callback is called for all client-to-server connect operations instead of the built-in socket connect code. Therefore, it can be used to override the built-in connection establishment. Parameter <i>endpoint</i> contains the server endpoint URL, <i>host</i> the domain name or IP, and <i>port</i> the port number.
Should return SOAP_OK, or a gSOAP error code.
Built-in gSOAP function: none
</td></tr>
<tr><td align="left"><i>SOAP_SOCKET (*soap.faccept)(<b>struct</b>&nbsp;soap *soap, SOAP_SOCKERT s, <b>struct</b>&nbsp;sockaddr *a, <b>int</b>&nbsp;*n)</i> </td></tr>
<tr><td align="left">Called by <i>soap_accept</i>. This is a wrapper routine for <i>accept</i>.
Given master socket <i>s</i> should return a valid socket descriptor or <i>SOAP_INVALID_SOCKET</i> and set <i>soap</i><tt>-&gt;</tt><i>error</i> to an error code.
Built-in gSOAP function: <i>tcp_accept</i>
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fresolve)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*addr, <b>struct</b>&nbsp;in_addr *inaddr)</i> </td></tr>
<tr><td align="left">Called by <i>soap_bind</i> if a host name is given and <i>soap_connect</i> to resolve a domain name <i>addr</i>.
Should set <i>in_addr *a</i> and return <i>SOAP_OK</i> or return <i>SOAP_ERR</i> upon failure.
</td></tr>
<tr><td align="left">Built-in gSOAP function: <i>tcp_gethost</i> </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fpoll)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Used by clients to check if the server is still responsive.
</td></tr>
<tr><td align="left">Built-in gSOAP function: <i>soap_poll</i> </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fserveloop)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Called after successful invocation of a server operation in the server loop, immediately after sending the response to a client.
Can be used to clean up resources (e.g.&nbsp;using <i>soap_end()</i>) while serving a long sequence of keep-alive connections.
Should return <i>SOAP_OK</i>, or set <i>soap</i><tt>-&gt;</tt><i>error</i> to a gSOAP error code and return <i>soap</i><tt>-&gt;</tt><i>error</i>.
Built-in gSOAP function: none.
</td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;(*soap.fmalloc)(<b>struct</b>&nbsp;soap *soap, size_t n)</i> </td></tr>
<tr><td align="left">Use to override memory allocation for deserialized C data. Memory allocated via
this callback will <em>not</em> be automatically released by the gSOAP engine. The
application must release this data by keeping track of the allocations. Note:
it is not safe to traverse deserialized data structures and free each node,
since data might be shared (SOAP multiref) and some allocated data such as the
HTTP SOAPAction might no be part of the structure.

<div class="p"><!----></div>
Built-in gSOAP function: none.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fheader)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Called immediately after parsing a SOAP Header. The SOAP Header struct referenced by <i>soap</i><tt>-&gt;</tt><i>header</i> can be inspected and verified. The function should return <i>SOAP_OK</i> or a fault.

<div class="p"><!----></div>
Built-in gSOAP function: none.
</td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;(*soap.fsvalidate)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*pattern, <b>const</b>&nbsp;<b>char</b>&nbsp;*string)</i> </td></tr>
<tr><td align="left">Called to validate a non-NULL string against a non-NULL pattern. Patterns use XML schema regex syntax. Allows user-defined pattern validation. Should return <i>SOAP_OK</i> when the string matches the pattern or <i>SOAP_PATTERN</i> when the string does not match.

<div class="p"><!----></div>
Built-in gSOAP function: none.
</td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;(*soap.fwvalidate)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*pattern, <b>const</b>&nbsp;wchar_t *string)</i> </td></tr>
<tr><td align="left">Called to validate a non-NULL wide string against a non-NULL pattern. Patterns use XML schema regex syntax. Allows user-defined pattern validation. Should return <i>SOAP_OK</i> when the string matches the pattern or <i>SOAP_PATTERN</i> when the string does not match.

<div class="p"><!----></div>
Built-in gSOAP function: none.
</td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;(*soap.fseterror)(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;**code, <b>const</b>&nbsp;<b>char</b>&nbsp;**string)</i> </td></tr>
<tr><td align="left">Called to set the SOAP Fault <i>code</i> and <i>string</i> values based on the value of <i>soap</i><tt>-&gt;</tt><i>error</i>. Allows user-defined messages to be associated with gSOAP error codes to override gSOAP's built-in error messages.

<div class="p"><!----></div>
Built-in gSOAP function: none.
</td></tr></table>

</td></tr></table><br></span>
In addition, a <i><b>void</b>*user</i> field in the <i><b>struct</b>&nbsp;soap</i> data structure is available to pass user-defined data to the callbacks.

<div class="p"><!----></div>
The following example uses I/O function callbacks for customized serialization of data into a fixed-size buffer and deserialization back into a
datastructure:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>char</b>&nbsp;buf[10000]; // XML buffer <br />
<b>int</b>&nbsp;len1 = 0;	// #chars written <br />
<b>int</b>&nbsp;len2 = 0;	// #chars read <br />
// mysend: put XML in buf[] <br />
<b>int</b>&nbsp;mysend(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*s, size_t n) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(len1 + n  &gt;  <b>sizeof</b>(buf)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_EOF; <br />
&nbsp;&nbsp;&nbsp;strcpy(buf + len1, s); <br />
&nbsp;&nbsp;&nbsp;len1 += n; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
// myrecv: get XML from buf[] <br />
size_t myrecv(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*s, size_t n) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(len2 + n  &gt;  len1) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;n = len1 - len2; <br />
&nbsp;&nbsp;&nbsp;strncpy(s, buf + len2, n); <br />
&nbsp;&nbsp;&nbsp;len2 += n; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;n; <br />
} <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;ns__person p; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;len1 = len2 = 0;	// reset buffer pointers <br />
&nbsp;&nbsp;&nbsp;p.name = "John Doe"; <br />
&nbsp;&nbsp;&nbsp;p.age = 25; <br />
&nbsp;&nbsp;&nbsp;soap.fsend = mysend; // assign callback <br />
&nbsp;&nbsp;&nbsp;soap.frecv = myrecv; // assign callback <br />
&nbsp;&nbsp;&nbsp;soap_begin_send(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_set_omode(&amp;soap, SOAP_XML_TREE); <br />
&nbsp;&nbsp;&nbsp;soap_serialize_ns__person(&amp;soap, &amp;p); <br />
&nbsp;&nbsp;&nbsp;soap_put_ns__person(&amp;soap, &amp;p, "ns:person", NULL); <br />
&nbsp;&nbsp;&nbsp;soap_end_send(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap.error) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stdout); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap_begin_recv(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_get_ns__person(&amp;soap, &amp;p, "ns:person", NULL); <br />
&nbsp;&nbsp;&nbsp;soap_end_recv(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap.error) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stdout); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap_destroy(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); // disable callbacks <br />
}
</td></tr></table><br></i>
A fixed-size buffer to store the outbound message sent is not flexible to handle large content. To store the message in an expanding buffer, use for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;buffer <br />
{ <br />
&nbsp;&nbsp;&nbsp;size_t len; <br />
&nbsp;&nbsp;&nbsp;size_t max; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*buf; <br />
}; <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;buffer *h = malloc(<b>sizeof</b>(<b>struct</b>&nbsp;buffer)); <br />
&nbsp;&nbsp;&nbsp;h<tt>-&gt;</tt>len = 0; <br />
&nbsp;&nbsp;&nbsp;h<tt>-&gt;</tt>max = 0; <br />
&nbsp;&nbsp;&nbsp;h<tt>-&gt;</tt>buf = NULL; <br />
&nbsp;&nbsp;&nbsp;soap.user = (<b>void</b>&nbsp;*)h; // pass buffer as a handle to the callback <br />
&nbsp;&nbsp;&nbsp;soap.fsend = mysend; // assign callback <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(h<tt>-&gt;</tt>len) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... // use h<tt>-&gt;</tt>buf[0..h<tt>-&gt;</tt>len-1] content <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// then cleanup: <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;h<tt>-&gt;</tt>len = 0; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;h<tt>-&gt;</tt>max = 0; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;free(h<tt>-&gt;</tt>buf); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;h<tt>-&gt;</tt>buf = NULL; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;... <br />
} <br />
<b>int</b>&nbsp;mysend(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*s, size_t n) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;buffer *h = (<b>struct</b>&nbsp;buffer*)soap<tt>-&gt;</tt>user; // get buffer through handle <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;m = h<tt>-&gt;</tt>max, k = h<tt>-&gt;</tt>len + n; <br />
&nbsp;&nbsp;&nbsp;// need to increase space? <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(m == 0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;m = 1024; <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>while</b>&nbsp;(k <tt>&gt;=</tt> m) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;m *= 2; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(m != h<tt>-&gt;</tt>max) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*buf = malloc(m); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;memcpy(buf, h<tt>-&gt;</tt>buf, h<tt>-&gt;</tt>len); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;h<tt>-&gt;</tt>max = m; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>(h<tt>-&gt;</tt>buf) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;free(h<tt>-&gt;</tt>buf); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;h<tt>-&gt;</tt>buf = buf; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;memcpy(h<tt>-&gt;</tt>buf + h<tt>-&gt;</tt>len, s, n); <br />
&nbsp;&nbsp;&nbsp;h<tt>-&gt;</tt>len += n; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
The <i>soap_done</i> function can be called to reset the callback to the default internal gSOAP I/O and HTTP handlers.

<div class="p"><!----></div>
The following example illustrates customized I/O and (HTTP) header handling. The SOAP request is saved to a file. The client proxy
then reads the file contents as the service response. To perform this trick, the service response has exactly the same structure as the
request. This is declared by the <i><b>struct</b>&nbsp;ns__test</i> output parameter part of the service operation declaration.
This struct resembles the service request (see the generated <i>soapStub.h</i> file created from the header file).

<div class="p"><!----></div>
The header file is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service name: callback <br />
//gsoap ns service namespace: urn:callback <br />
<b>struct</b>&nbsp;ns__person <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;age; <br />
}; <br />
<b>int</b>&nbsp;ns__test(<b>struct</b>&nbsp;ns__person in, <b>struct</b>&nbsp;ns__test &amp;out);
</td></tr></table><br></i>
The client program is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "soapH.h" <br />
... <br />
SOAP_SOCKET myopen(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*endpoint, <b>const</b>&nbsp;<b>char</b>&nbsp;*host, <b>int</b>&nbsp;port) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(strncmp(endpoint, "file:", 5)) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf("File name expected<tt>\</tt>n"); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_INVALID_SOCKET; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;((soap<tt>-&gt;</tt>sendfd = soap<tt>-&gt;</tt>recvfd = open(host, O_RDWR | O_CREAT, S_IWUSR | S_IRUSR))  &lt;  0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_INVALID_SOCKET; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap<tt>-&gt;</tt>sendfd; <br />
} <br />
<b>void</b>&nbsp;myclose(<b>struct</b>&nbsp;soap *soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;if (soap<tt>-&gt;</tt>sendfd  &gt;  2) // still open? <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;close(soap<tt>-&gt;</tt>sendfd); // then close it <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>recvfd = 0; // set back to stdin <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>sendfd = 1; // set back to stdout <br />
} <br />
<b>int</b>&nbsp;mypost(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*endpoint, <b>const</b>&nbsp;<b>char</b>&nbsp;*host, <b>const</b>&nbsp;<b>char</b>&nbsp;*path, <b>const</b>&nbsp;<b>char</b>&nbsp;*action, size_t count) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_send(soap, "Custom-generated file<tt>\</tt>n"); // writes to soap<tt>-&gt;</tt>sendfd <br />
} <br />
<b>int</b>&nbsp;myparse(<b>struct</b>&nbsp;soap *soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;buf[256]; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(lseek(soap<tt>-&gt;</tt>recvfd, 0, SEEK_SET)  &lt;  0 <tt>||</tt> soap_getline(soap, buf, 256)) // go to begin and skip custom header <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_EOF; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;ns__test r; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;ns__person p; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); // reset <br />
&nbsp;&nbsp;&nbsp;p.name = "John Doe"; <br />
&nbsp;&nbsp;&nbsp;p.age = 99; <br />
&nbsp;&nbsp;&nbsp;soap.fopen = myopen; // use custom open <br />
&nbsp;&nbsp;&nbsp;soap.fpost = mypost; // use custom post <br />
&nbsp;&nbsp;&nbsp;soap.fparse = myparse; // use custom response parser <br />
&nbsp;&nbsp;&nbsp;soap.fclose = myclose; // use custom close <br />
&nbsp;&nbsp;&nbsp;soap_call_ns__test(&amp;soap, "file://test.xml", "", p, r); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap.error) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stdout); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); // reset to default callbacks <br />
}
</td></tr></table><br></i>
SOAP 1.1 and 1.2 specify that XML elements may be ignored when present in a SOAP payload on the receiving side.
gSOAP ignores XML elements that are unknown, unless the XML attribute <tt>mustUnderstand="true"</tt> is present in the XML element.
It may be undesirable for elements to be ignored when the outcome of the omission is uncertain.
The <i>soap.fignore</i> callback can be set to a function that returns <i>SOAP_OK</i> in case the element can be safely ignored, or
<i>SOAP_MUSTUNDERSTAND</i> to throw an exception, or to perform some application-specific action.
For example, to throw an exception as soon as an unknown element is encountered on the input, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;myignore(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*tag) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_MUSTUNDERSTAND; // never skip elements (secure) <br />
} <br />
... <br />
soap.fignore = myignore; <br />
soap_call_ns__method(&amp;soap, ...); // or soap_serve(&amp;soap);
</td></tr></table><br></i>
To selectively throw an exception as soon as an unknown element is encountered but element <tt>ns:xyz</tt> can be safely ignored, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;myignore(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*tag) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_match_tag(soap, tag, "ns:xyz") != SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_MUSTUNDERSTAND; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
... <br />
soap.fignore = myignore; <br />
soap_call_ns__method(&amp;soap, ...); // or soap_serve(&amp;soap) <br />
... <br />
<b>struct</b>&nbsp;Namespace namespaces[] = <br />
{ <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/"}, <br />
&nbsp;&nbsp;&nbsp;{"SOAP-ENC","http://schemas.xmlsoap.org/soap/encoding/"}, <br />
&nbsp;&nbsp;&nbsp;{"xsi", "http://www.w3.org/2001/XMLSchema-instance"}, <br />
&nbsp;&nbsp;&nbsp;{"xsd", "http://www.w3.org/2001/XMLSchema"}, <br />
&nbsp;&nbsp;&nbsp;{"ns", "some-URI"}, // the namespace of element ns:xyz <br />
&nbsp;&nbsp;&nbsp;{NULL, NULL} <br />
</td></tr></table><br></i>
Function <i>soap_match_tag</i> compares two tags. The third parameter may be a pattern where <i>*</i> is a wildcard
and <i>-</i> is a single character wildcard. So for example
<i>soap_match_tag(tag, "ns:*")</i> will match any element in namespace <i>ns</i> or when no namespace prefix is present in the XML
message.

<div class="p"><!----></div>
The callback can also be used to keep track of unknown elements in an internal data structure such as a list:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;Unknown <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*tag; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;Unknown *next; <br />
}; <br />
<b>int</b>&nbsp;myignore(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*tag) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*s = (<b>char</b>*)soap_malloc(soap, strlen(tag)+1); <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;Unknown *u = (<b>struct</b>&nbsp;Unknown*)soap_malloc(soap, <b>sizeof</b>(<b>struct</b>&nbsp;Unknown)); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(s &amp;&amp; u) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;strcpy(s, tag); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;u<tt>-&gt;</tt>tag = s; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;u<tt>-&gt;</tt>next = ulist; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ulist = u; <br />
&nbsp;&nbsp;&nbsp;} <br />
} <br />
... <br />
<b>struct</b>&nbsp;soap *soap; <br />
<b>struct</b>&nbsp;Unknown *ulist = NULL; <br />
soap_init(&amp;soap); <br />
soap.fignore = myignore; <br />
soap_call_ns__method(&amp;soap, ...); // or soap_serve(&amp;soap) <br />
// print the list of unknown elements <br />
soap_end(&amp;soap); // clean up
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.8">
19.8</a>&nbsp;&nbsp;<font color="#0000FF">HTTP 1.0 and 1.1</font></h3>

<div class="p"><!----></div>
gSOAP uses HTTP 1.1 by default. You can revert to HTTP 1.0 as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
... <br />
soap.http_version = "1.0";
</td></tr></table><br></i>
This sets the HTTP version and reconfigures the engine to revert to HTTP 1.0.
Note that you cannot use HTTP chunking with HTTP 1.0.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.9">
19.9</a>&nbsp;&nbsp;<font color="#0000FF">HTTP 307 Temporary Redirect Support</font></h3>

<div class="p"><!----></div>
The client-side handling of HTTP 307 code "Temporary Redirect" and any of the redirect codes 301, 302, and 303 are not automated in gSOAP. Client application developers may want to consider adding a few lines of code to support redirects. It was decided not to automatically support redirects for the following reasons:

<ul>
<li> Redirecting a secure HTTPS address to a non-secure HTTP address via 307 creates a security vulnerability.
<div class="p"><!----></div>
</li>

<li> Cyclic redirects must be detected (e.g. allowing only a limited number of redirect levels).
<div class="p"><!----></div>
</li>

<li> Redirecting HTTP POST will result in re-serialization and re-post of the entire SOAP request. The SOAP request message must be re-posted in its entirity when re-issuing the SOAP operation to a new address.
<div class="p"><!----></div>
</li>
</ul>
To implement client-side 307 redirect, add the following lines of code:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>char</b>&nbsp;*endpoint = NULL; // use default endpoint given in WSDL (or add another one here) <br />
<b>int</b>&nbsp;n = 10; // max redirect count <br />
<b>while</b>&nbsp;(n&#8722;&nbsp;&#8722;) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_ns1__myMethod(soap, endpoint, ...)) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;((soap<tt>-&gt;</tt>error <tt>&gt;=</tt> 301 <tt>&amp;&amp;</tt> soap<tt>-&gt;</tt>error <tt>&lt;=</tt> 303) <tt>||</tt> soap<tt>-&gt;</tt>error == 307) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;endpoint = soap_strdup(soap, soap<tt>-&gt;</tt>endpoint); // endpoint from HTTP 301, 302, 303, 307 Location header <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ ... report and handle error <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.10">
19.10</a>&nbsp;&nbsp;<font color="#0000FF">HTTP GET Support</font></h3><a name="sec:get">
</a>

<div class="p"><!----></div>
To implement your own HTTP (HTTPS) GET request responses, you need to set the <i>soap.fget</i> callback. The callback is required to produce a response to the request in textual form, such as a Web page or a SOAP/XML response. This method does not work with CGI.

<div class="p"><!----></div>
The following example produces a Web page upon a HTTP GET request (e.g. from a browser):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap *soap = soap_new(); <br />
soap<tt>-&gt;</tt>fget = http_get; <br />
... <br />
soap_serve(soap); <br />
... <br />
<b>int</b>&nbsp;http_get(<b>struct</b>&nbsp;soap *soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_response(soap, SOAP_HTML); // HTTP response header with text/html <br />
&nbsp;&nbsp;&nbsp;soap_send(soap, "&lt;HTML&#62;My Web server is operational.&lt;/HTML&#62;"); <br />
&nbsp;&nbsp;&nbsp;soap_end_send(soap); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
The example below produces a WSDL file upon a HTTP GET with path <i>?wsdl</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;http_get(<b>struct</b>&nbsp;soap *soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;FILE *fd = NULL;<br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*s = strchr(soap<tt>-&gt;</tt>path, '?'); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!s <tt>||</tt> strcmp(s, "?wsdl")) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_GET_METHOD; <br />
&nbsp;&nbsp;&nbsp;fd = fopen("myservice.wsdl", "rb"); // open WSDL file to copy <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!fd) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;404; // return HTTP not found error <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>http_content = "text/xml"; // HTTP header with text/xml content <br />
&nbsp;&nbsp;&nbsp;soap_response(soap, SOAP_FILE); <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(;;) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;size_t r = fread(soap<tt>-&gt;</tt>tmpbuf, 1, sizeof(soap<tt>-&gt;</tt>tmpbuf), fd); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!r) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_send_raw(soap, soap<tt>-&gt;</tt>tmpbuf, r)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; // can't send, but little we can do about that <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;fclose(fd); <br />
&nbsp;&nbsp;&nbsp;soap_end_send(soap); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
Using one-way SOAP/XML message, you can also return a SOAP/XML response:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;http_get(<b>struct</b>&nbsp;soap *soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;((soap<tt>-&gt;</tt>omode &amp; SOAP_IO) != SOAP_IO_CHUNK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_set_omode(soap, SOAP_IO_STORE); // if not chunking we MUST buffer entire content to determine content length <br />
&nbsp;&nbsp;&nbsp;soap_response(soap, SOAP_OK); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap_send_ns1__mySendMethodResponse(soap, "", NULL, ... params ...); <br />
} <br />
</td></tr></table><br></i>
where <i>ns1__mySendMethodResponse</i> is a one-way message declared in a gSOAP header file as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns1__mySendMethodResponse(... params ..., <b>void</b>);
</td></tr></table><br></i>
The generated <i>soapClient.cpp</i> includes the sending-side stub function.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.11">
19.11</a>&nbsp;&nbsp;<font color="#0000FF">TCP and HTTP Keep-Alive</font></h3><a name="sec:keepalive">
</a>

<div class="p"><!----></div>
gSOAP supports keep-alive socket connections. To activate keep-alive support,
set the <i>SOAP_IO_KEEPALIVE</i> flag for both input and output modes, see Section&nbsp;<a href="#sec:flags">9.12</a>.
For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init2(&amp;soap, SOAP_IO_KEEPALIVE, SOAP_IO_KEEPALIVE); <br />
</td></tr></table><br></i>
When a client or a service communicates with another client or service that supports keep alive, the
attribute <i>soap.keep_alive</i> will be set to 1, otherwise it is reset to 0 (indicating that the other party 
will close the connection).
The connection maybe terminated on either end before the communication completed, for example when the server keep-alive
connection has timed out.
This generates a "Broken Pipe" signal on Unix/Linux platforms. This signal can be caught with a signal handler:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
signal(SIGPIPE, sigpipe_handle);
</td></tr></table><br></i>
where, for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>void</b>&nbsp;sigpipe_handle(<b>int</b>&nbsp;x) { }
</td></tr></table><br></i>
Alternatively, broken pipes can be kept silent by setting:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap.socket_flags = MSG_NOSIGNAL;
</td></tr></table><br></i>
This setting will not generate a sigpipe but read/write operations return <i>SOAP_EOF</i> instead.
Note that Win32 systems do not support signals and lack the <i>MSG_NOSIGNAL</i> flag.
The sigpipe handling and flags are not very portable.

<div class="p"><!----></div>
A connection will be kept open only if the request contains an HTTP 1.0 header
with "<tt>Connection: Keep-Alive</tt>" or an HTTP 1.1 header that does not contain
"<tt>Connection: close</tt>". This means that a gSOAP client method call should
use "<tt>http://</tt>" in the endpoint URL of the request to the stand-alone
service to ensure HTTP headers are used.

<div class="p"><!----></div>
If the client does not close the connection, the server will wait forever when
no <i>recv_timeout</i> is specified.  In addition, other clients will be denied
service as long as a client keeps the connection to the server open.  To
prevent this from happening, the service should be multi-threaded such that
each thread handles the client connection:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main(<b>int</b>&nbsp;argc, <b>char</b>&nbsp;**argv) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap, *tsoap; <br />
&nbsp;&nbsp;&nbsp;pthread_t tid; <br />
&nbsp;&nbsp;&nbsp;int m, s; <br />
&nbsp;&nbsp;&nbsp;soap_init2(&amp;soap, SOAP_IO_KEEPALIVE, SOAP_IO_KEEPALIVE); <br />
&nbsp;&nbsp;&nbsp;soap.max_keep_alive = 100; // at most 100 calls per keep-alive session <br />
&nbsp;&nbsp;&nbsp;soap.accept_timeout = 600; // optional: let server time out after ten minutes of inactivity <br />
&nbsp;&nbsp;&nbsp;m = soap_bind(&amp;soap, NULL, 18000, BACKLOG); // use port 18000 on the current machine <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(m  &lt;  0) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Socket&nbsp;connection&nbsp;successful&nbsp;%d\n"</tt>, m); <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(count = 0; count <tt>&gt;=</tt> 0; count++) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.socket_flags = MSG_NOSIGNAL; // use this <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.accept_flags = SO_NOSIGPIPE; // or this to prevent sigpipe <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s = soap_accept(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(s  &lt;  0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap.errnum) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Server&nbsp;timed&nbsp;out\n"</tt>); // Assume timeout is long enough for threads to complete serving requests <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, <tt>"Accepts&nbsp;socket&nbsp;%d&nbsp;connection&nbsp;from&nbsp;IP&nbsp;%d.%d.%d.%d\n"</tt>, s, (<b>int</b>)(soap.ip &gt;&gt; 24)&amp;0xFF, (<b>int</b>)(soap.ip &gt;&gt; 16)&amp;0xFF, (<b>int</b>)(soap.ip &gt;&gt; 8)&amp;0xFF, (<b>int</b>)soap.ip&amp;0xFF); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tsoap = soap_copy(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_create(&amp;tid, NULL, (void*(*)(void*))process_request, (void*)tsoap); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
} <br />
<b>void</b>&nbsp;*process_request(<b>void</b>&nbsp;*soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;pthread_detach(pthread_self()); <br />
&nbsp;&nbsp;&nbsp;((<b>struct</b>&nbsp;soap*)soap)<tt>-&gt;</tt>recv_timeout = 300; // Timeout after 5 minutes stall on recv <br />
&nbsp;&nbsp;&nbsp;((<b>struct</b>&nbsp;soap*)soap)<tt>-&gt;</tt>send_timeout = 60; // Timeout after 1 minute stall on send <br />
&nbsp;&nbsp;&nbsp;soap_serve((<b>struct</b>&nbsp;soap*)soap); <br />
&nbsp;&nbsp;&nbsp;soap_destroy((<b>struct</b>&nbsp;soap*)soap); <br />
&nbsp;&nbsp;&nbsp;soap_end((<b>struct</b>&nbsp;soap*)soap); <br />
&nbsp;&nbsp;&nbsp;soap_free((<b>struct</b>&nbsp;soap*)soap); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;NULL; <br />
}
</td></tr></table><br></i>
To prevent a malicious client from keeping a thread waiting forever by keeping
the connection open, timeouts are set in the <i>process_request</i> routine as
shown.  See Section&nbsp;<a href="#sec:timeout">19.19</a> for more details on timeout settings.

<div class="p"><!----></div>
A gSOAP client call will automatically attempt to re-establish a connection to
a server when the server has terminated the connection for any reason.  This
way, a sequence of calls can be made to the server while keeping the connection
open.  Client stubs will poll the server to check if the connection is still
open.  When the connection was terminated by the server, the client will
automatically reconnect.  

<div class="p"><!----></div>
A client should reset <i>SOAP_IO_KEEPALIVE</i> just before the last call to a
server to close the connection after this last call. This will close the socket
after the call and also informs the server to gracefully close the connection.

<div class="p"><!----></div>
The client-side can also set the TCP keep-alive socket properties, using the <i>soap.tcp_keep_alive</i> flag (set to 1 to enable), <i>soap.tcp_keep_idle</i> to set the TCP_KEEPIDLE value, <i>soap.tcp_keep_intvl</i> to set the TCP_KEEPINTVL value, and <i>soap.tcp_keep_cnt</i> to set the TCP_KEEPCNT value.

<div class="p"><!----></div>
If a client is in the middle of soap call that might take a long time and the
server goes away/down the caller does not get any feedback until the
<i>soap.recv_timeout</i> is reached. Enabling TCP keep alive on systems that
support it allows for a faster connection teardown detection for applications
that need it.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.12">
19.12</a>&nbsp;&nbsp;<font color="#0000FF">HTTP Chunked Transfer Encoding</font></h3><a name="sec:chunked">
</a>

<div class="p"><!----></div>
gSOAP supports HTTP chunked transfer encoding. Un-chunking of inbound messages
takes place automatically. Outbound messages are never chunked, except when the
<i>SOAP_IO_CHUNK</i> flag is set for the output mode.  Most Web services,
however, will not accept chunked inbound messages.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.13">
19.13</a>&nbsp;&nbsp;<font color="#0000FF">HTTP Buffered Sends</font></h3>

<div class="p"><!----></div>
The entire outbound message can be stored to determine the HTTP content length
rather than the two-phase encoding used by gSOAP which requires a separate pass
over the data to determine the length of the outbound message.  Setting the
flag <i>SOAP_IO_STORE</i> for the output mode will buffer the entire message.
This can speed up the transmission of messages, depending on the content, but
may require significant storage space to hold the verbose XML message.

<div class="p"><!----></div>
Zlib compressed transfers require buffering. The <i>SOAP_IO_STORE</i> flag is
set when the <i>SOAP_ENC_ZLIB</i> flag is set to send compressed messages. The use of chunking
significantly reduces memory usage and may speed up the transmission of compressed SOAP/XML messages.
This is accomplished by setting the <i>SOAP_IO_CHUNK</i> flag with
<i>SOAP_ENC_ZLIB</i> for the output mode.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.14">
19.14</a>&nbsp;&nbsp;<font color="#0000FF">HTTP Authentication</font></h3>

<div class="p"><!----></div>
HTTP authentication (basic) is enabled at the client-side by setting the
<i>soap.userid</i> and <i>soap.passwd</i> strings to a username and password,
respectively.  A server may request user authentication
and denies access (HTTP 401 error) when the client tries to connect without HTTP authentication (or with the wrong authentication information).

<div class="p"><!----></div>
Here is an example client code fragment to set the HTTP authentication username and password:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
soap.userid = "guest"; <br />
soap.passwd = "visit"; <br />
...
</td></tr></table><br></i>
A client SOAP request will have the following HTTP header:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
POST /XXX HTTP/1.0 <br />
Host: YYY <br />
User-Agent: gSOAP/2.2 <br />
Content-Type: text/xml; charset=utf-8 <br />
Content-Length: nnn <br />
Authorization: Basic Z3Vlc3Q6Z3Vlc3Q= <br />
...
</td></tr></table><br></tt>
A client MUST set the <i>soap.userid</i> and <i>soap.passwd</i> strings for each call that requires client authentication. The strings are reset after each successful or unsuccessful call.

<div class="p"><!----></div>
When present, the value of the <i>WWW-Authenticate</i> HTTP header with the authentication realm can be obtained from the <i>soap.authrealm</i> string. This is useful for clients to respond intelligently to authentication requests.

<div class="p"><!----></div>
A stand-alone gSOAP Web Service can enforce HTTP authentication upon clients, by checking the <i>soap.userid</i> and <i>soap.passwd</i> strings. These strings are set when a client request contains HTTP authentication headers. The strings SHOULD be checked in each service method (that requires authentication to execute).

<div class="p"><!----></div>
Here is an example service method implementation that enforced client authentication:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__method(<b>struct</b>&nbsp;soap *soap, ...) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap<tt>-&gt;</tt>.userid <tt>||</tt> !soap<tt>-&gt;</tt>.passwd <tt>||</tt>
strcmp(soap<tt>-&gt;</tt>.userid, "guest") <tt>||</tt>
strcmp(soap<tt>-&gt;</tt>.passwd, "visit")) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;401; <br />
... <br />
}
</td></tr></table><br></i>
When the authentication fails, the service response with a SOAP Fault message and a HTTP error code "401 Unauthorized".
The HTTP error codes are described in Section&nbsp;<a href="#sec:errcodes">10.2</a>.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.15">
19.15</a>&nbsp;&nbsp;<font color="#0000FF">HTTP NTLM Authentication</font></h3>

<div class="p"><!----></div>
HTTP NTLM authentication is enabled at the client-side by installing
<i>libntlm</i> from <a href="http://www.nongnu.org/libntlm"><tt>http://www.nongnu.org/libntlm</tt></a> and compiling all
project source codes with <i>-DWITH_NTLM</i>.

<div class="p"><!----></div>
In your application code set the <i>soap.userid</i>, <i>soap.passwd</i>, and
<i>soap.authrealm</i> strings to a username, password,
and the authentication domain respectively. A server may request NTLM
authentication and denies access (HTTP 401 authentication required or HTTP 407 HTTP proxy authentication required) when the client tries to
connect without HTTP authentication (or with the wrong authentication
information).

<div class="p"><!----></div>
Here is an example client code fragment to set the NTLM authentication username and password:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init1(&amp;soap, SOAP_IO_KEEPALIVE); <br />
<b>if</b>&nbsp;(soap_call_ns__method(&amp;soap, ...)) <br />
{ <b>if</b>&nbsp;(soap.error == 401) <br />
&nbsp;&nbsp;&nbsp;{ soap.userid = "Zaphod"; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.passwd = "Beeblebrox"; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.authrealm = "Ursa-Minor"; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_ns__method(&amp;soap, ...)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...
</td></tr></table><br></i>
The following NTLM handshake between the client C and server S is performed:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>

<table>
<tr><td align="left">1: C  -&#62; S </td><td align="left">POST ... </td></tr>
<tr><td align="left"></td><td align="left">Content-Type: text/xml; charset=utf-8 </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left">2: C &lt;-  S </td><td align="left">401 Unauthorized </td></tr>
<tr><td align="left"></td><td align="left">WWW-Authenticate: NTLM </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left">3: C  -&#62; S </td><td align="left">GET ... </td></tr>
<tr><td align="left"></td><td align="left">Authorization: NTLM &lt;base64-encoded type-1-message&#62; </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left">4: C &lt;-  S </td><td align="left">401 Unauthorized </td></tr>
<tr><td align="left"></td><td align="left">WWW-Authenticate: NTLM &lt;base64-encoded type-2-message&#62; </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left">5: C  -&#62; S </td><td align="left">POST ... </td></tr>
<tr><td align="left"></td><td align="left">Content-Type: text/xml; charset=utf-8 </td></tr>
<tr><td align="left"></td><td align="left">Authorization: NTLM &lt;base64-encoded type-3-message&#62; </td></tr>
<tr><td align="left"></td></tr>
<tr><td align="left">6: C &lt;-  S </td><td align="left">200 OK
</td></tr></table>

</td></tr></table><br></tt>
where stages 1 and 2 indicates a client attempting to connect without
authorization information, which is the first method call in the code above. Stage 3 to 6 happen with the proper client
authentication set with <i>soap.userid</i>, <i>soap.passwd</i>, and
<i>soap.authrealm</i> provided. NTLM authenticates connections, not requests. When the connection is kept alive, subsequent messages can be exchanged without re-authentication.

<div class="p"><!----></div>
To avoid the overhead of the first rejected call, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init1(&amp;soap, SOAP_IO_KEEPALIVE); <br />
soap.userid = "Zaphod"; <br />
soap.passwd = "Beeblebrox"; <br />
soap.authrealm = "Ursa-Minor"; <br />
soap.ntlm_challenge = ""; <br />
<b>if</b>&nbsp;(soap_call_ns__method(&amp;soap, ...)) <br />
&nbsp;&nbsp;&nbsp;...
</td></tr></table><br></i>

<div class="p"><!----></div>
When the authentication fails (stage 1 and 2), the service response with a SOAP
Fault message and a HTTP error code "401 Unauthorized". The HTTP error codes
are described in Section&nbsp;<a href="#sec:errcodes">10.2</a>.

<div class="p"><!----></div>
On windows, an alternative is to use the WinInet module, which has built-in
NTLM support. The WinInet for gSOAP module is available in the <i>mod_gsoap</i>
directory of the gSOAP package. Instructions for WinInet use are included there.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.16">
19.16</a>&nbsp;&nbsp;<font color="#0000FF">HTTP Proxy NTLM Authentication</font></h3>

<div class="p"><!----></div>
For HTTP 407 Proxy Authentication Required, set the proxy userid and passwd:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init1(&amp;soap, SOAP_IO_KEEPALIVE); <br />
soap.proxy_host = "..."; <br />
soap.proxy_port = ...; <br />
<b>if</b>&nbsp;(soap_call_ns__method(&amp;soap, ...)) <br />
{ <b>if</b>&nbsp;(soap.error == 407) <br />
&nbsp;&nbsp;&nbsp;{ soap.proxy_userid = "Zaphod"; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.proxy_passwd = "Beeblebrox"; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap.authrealm = "Ursa-Minor"; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_ns__method(&amp;soap, ...)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...
</td></tr></table><br></i>
To avoid the overhead of the first rejected call, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init1(&amp;soap, SOAP_IO_KEEPALIVE); <br />
soap.proxy_host = "..."; <br />
soap.proxy_port = ...; <br />
soap.proxy_userid = "Zaphod"; <br />
soap.proxy_passwd = "Beeblebrox"; <br />
soap.authrealm = "Ursa-Minor"; <br />
soap.ntlm_challenge = ""; <br />
<b>if</b>&nbsp;(soap_call_ns__method(&amp;soap, ...)) <br />
&nbsp;&nbsp;&nbsp;...
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.17">
19.17</a>&nbsp;&nbsp;<font color="#0000FF">HTTP Proxy Basic Authentication</font></h3>

<div class="p"><!----></div>
HTTP proxy authentication (basic) is enabled at the client-side by setting the
<i>soap.proxy_userid</i> and <i>soap.proxy_passwd</i> strings to a username and
password, respectively.  For example, a proxy server may request user
authentication. Otherwise, access is denied by the proxy (HTTP 407 error).
Example client code fragment to set proxy server, username, and password:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
soap.proxy_host = "xx.xx.xx.xx"; // IP or domain <br />
soap.proxy_port = 8080; <br />
soap.proxy_userid = "guest"; <br />
soap.proxy_passwd = "guest"; <br />
...
</td></tr></table><br></i>
A client SOAP request will have the following HTTP header:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
POST /XXX HTTP/1.0 <br />
Host: YYY <br />
User-Agent: gSOAP/2.2 <br />
Content-Type: text/xml; charset=utf-8 <br />
Content-Length: nnn <br />
Proxy-Authorization: Basic Z3Vlc3Q6Z3Vlc3Q= <br />
...
</td></tr></table><br></tt>
When X-Forwarded-For headers are returned by the proxy, the header can be accessed in the <i>soap.proxy_from</i> string.

<div class="p"><!----></div>
The CONNECT method is used for HTTP proxy authentication:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
CONNECT server.example.com:80 HTTP/1.1
</td></tr></table><br></tt>
In some cases, it may be necessary to use the Host HTTP header with the CONNECT
protocol:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0B0D0"><tr><td><tt>
CONNECT server.example.com:80 HTTP/1.1 <br />
Host: server.example.com:80
</td></tr></table><br></tt>
If so, compile the gSOAP code with <i>-DWITH_CONNECT_HOST</i> to include the
Host HTTP header with the CONNECT protocol.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.18">
19.18</a>&nbsp;&nbsp;<font color="#0000FF">Messaging Speed and Performance Improvement Tips</font></h3>

<div class="p"><!----></div>
Here are some tips you can use to speed up gSOAP. gSOAP's default settings are choosen to maximize portability and compatibility. The settings can be tweaked to optimize the performance as follows:

<ul>
<li> Increase the buffer size <i>SOAP_BUFLEN</i> by changing the <i>SOAP_BUFLEN</i> macro in <i>stdsoap2.h</i>. Use buffer size 2<sup>1</sup>8=262144 for example.
<div class="p"><!----></div>
</li>

<li> Use HTTP keep-alive at the client-side, see&nbsp;<a href="#sec:keepalive">19.11</a>, when the client needs to make a series of calls to the same server. Server-side keep-alive support can greatly improve performance of both client and server. But be aware that clients and services under Unix/Linux require signal handlers to catch dropped connections.
<div class="p"><!----></div>
</li>

<li> Use HTTP chunked transfers, see&nbsp;<a href="#sec:chunked">19.12</a>.
<div class="p"><!----></div>
</li>

<li> Do NOT use gzip compression, since the overhead of compression is typically higher than the bandwidth gains.
<div class="p"><!----></div>
</li>

<li> Set the <i>SOAP_XML_TREE</i> flag to disable id-ref multi-ref object (de)serialization. This boosts performance significantly and works with SOAP document/literal style (i.e. no id-ref graph serialization as required with SOAP encoding style).
<div class="p"><!----></div>
</li>

<li> Compile <i>stdsoap2.c</i> and <i>stdsoap2.cpp</i> with <i>-DWITH_NOIDREF</i> to improve performance even better by permanently disabling id-ref multi-ref object (de)serialization.
<div class="p"><!----></div>
</li>

<li> Do NOT use DEBUG mode, since the overhead of logging is significant.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.19">
19.19</a>&nbsp;&nbsp;<font color="#0000FF">Timeout Management for Non-Blocking Operations</font></h3><a name="sec:timeout">
</a>

<div class="p"><!----></div>
Socket connect, accept, send, and receive timeout values can be set to manage
socket communication timeouts.  The <i>soap.connect_timeout</i>,
<i>soap.accept_timeout</i>, <i>soap.send_timeout</i>, and
<i>soap.recv_timeout</i> attributes of the current gSOAP runtime context
<i>soap</i> can be set to the appropriate user-defined socket send, receive, and
accept timeout values. A positive value measures the timeout in seconds. A
negative timeout value measures the timeout in microseconds (10<sup>&#8722;6</sup> sec).

<div class="p"><!----></div>
The <i>soap.connect_timeout</i> specifies the timeout for
<i>soap_call_ns__method</i> calls.

<div class="p"><!----></div>
The <i>soap.accept_timeout</i> specifies the timeout for
<i>soap_accept(&amp;soap)</i> calls.

<div class="p"><!----></div>
The <i>soap.send_timeout</i> and <i>soap.recv_timeout</i> specify the timeout
for non-blocking socket I/O operations.

<div class="p"><!----></div>
Example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
soap.send_timeout = 10; <br />
soap.recv_timeout = 10; 
</td></tr></table><br></i>
This will result in a timeout if no data can be send in 10 seconds and no data is received within 10 seconds after initiating
a send or receive operation over the socket. A value of zero disables timeout, for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap.send_timeout = 0; <br />
soap.recv_timeout = 0; 
</td></tr></table><br></i>
When a timeout occurs in send/receive operations, a <i>SOAP_EOF</i> exception will be raised ("end of file or no input").
Negative timeout values measure timeouts in microseconds, for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#define uSec *-1 <br />
#define mSec *-1000 <br />
soap.accept_timeout = 10 uSec; <br />
soap.send_timeout = 20 mSec; <br />
soap.recv_timeout = 20 mSec;
</td></tr></table><br></i>
The macros improve readability.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: many Linux versions do not support non-blocking <i>connect()</i>.
Therefore, setting <i>soap.connect_timeout</i> for non-blocking
<i>soap_call_ns__method</i> calls may not work under Linux.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: interrupts (EINTR) can affect the blocking time in I/O operations.
The maximum number of EINTR that will not trigger an error is set by
<i>SOAP_MAXEINTR</i> in <i>stdsoap2.h</i>, which is 10 by default. Each EINTR
may increase the blocking time by up to one second, up to <i>SOAP_MAXEINTR</i>
seconds total.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.20">
19.20</a>&nbsp;&nbsp;<font color="#0000FF">Socket Options and Flags</font></h3>

<div class="p"><!----></div>
gSOAP's socket communications can be controlled with socket options and flags.
The gSOAP run-time context <i><b>struct</b>&nbsp;soap</i> flags are:
<i><b>int</b>&nbsp;soap.socket_flags</i> to control socket send() and recv() calls,
<i><b>int</b>&nbsp;soap.connect_flags</i> to set client connection socket options,
<i><b>int</b>&nbsp;soap.bind_flags</i> to set server-side port bind socket options,
<i><b>int</b>&nbsp;soap.accept_flags</i> to set server-side request message accept
socket options. See the manual pages of <i>send</i> and <i>recv</i> for
<i>soap.socket_flags</i> values and see the manual pages of
<i>setsockopt</i> for
<i>soap.connect_flags</i>, <i>soap.bind_flags</i>, and
<i>soap.accept_flags</i> (SOL_SOCKET) values.
These <i>SO_</i> socket option flags (see <i>setsockopt</i> manual pages)
can be bit-wise or-ed to set multiple
socket options at once.
The client-side flag <i>soap.connect_flags=SO_LINGER</i> is supported with values <i>l_onoff=1</i> and <i>l_linger=soap.linger_time</i>. The <i>soap.linger_time</i> determines the wait time (the time resolution is system dependent, though according to some experts only zero and nonzero values matter). The linger option can be used to manage the number of connections that remain in TIME_WAIT state at the server side.

<div class="p"><!----></div>
For example, to disable sigpipe signals on Unix/Linux platforms use: 
<i>soap.socket_flags = MSG_NOSIGNAL</i> and/or
<i>soap.connect_flags = SO_NOSIGPIPE</i> (i.e.&nbsp;client-side connect) depending
on your platform.

<div class="p"><!----></div>
Use <i>soap.bind_flags=SO_REUSEADDR</i> to enable server-side port reuse and local port
sharing (but be aware of the possible security implications such as port hijacking).

<div class="p"><!----></div>
Note that multiple socket options can be explicitly set with <i>setsockopt</i> as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;sock = soap_bind(soap, host, port, backlog); <br />
<b>if</b>&nbsp;(soap_valid_socket(sock)) <br />
{ <br />
&nbsp;&nbsp;&nbsp;setsockopt(sock, ..., ..., ..., ...);
&nbsp;&nbsp;&nbsp;setsockopt(sock, ..., ..., ..., ...);
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.21">
19.21</a>&nbsp;&nbsp;<font color="#0000FF">Secure Web Services with HTTPS/SSL</font></h3>&nbsp;<a name="sec:serveropenssl">
</a>

<div class="p"><!----></div>
When a Web Service is installed as CGI, it uses standard I/O that is encrypted/decrypted by the Web server that runs the CGI
application.
HTTPS/SSL support must be configured for the Web server (not CGI-based Web Service application itself).

<div class="p"><!----></div>
To enable SSL for stand-alone gSOAP servers, first install OpenSSL and use option <i>-DWITH_OPENSSL</i> to compile the sources with your C or C++ compiler (or use <i>-DWITH_GNUTLS</i> if you prefer GNUTLS), for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -DWITH_OPENSSL -o myprog myprog.cpp stdsoap2.cpp soapC.cpp soapServer.cpp -lssl -lcrypto</i>
</td></tr></table><br></span>
SSL support for stand-alone gSOAP Web services is enabled by calling <i>soap_ssl_accept</i> to perform the SSL/TLS handshake after <i>soap_accept</i>.
In addition, a key file, a CA file (or path to certificates), DH file (if RSA is not used), and password need to be supplied. Instructions on how to do this can be found in the
OpenSSL documentation <i>http://www.openssl.org</i>. See also Section&nbsp;<a href="#sec:ssl">19.24</a>.

<div class="p"><!----></div>
Let's take a look at an example SSL secure
multi-threaded stand-alone SOAP Web Service:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;m, s; <br />
&nbsp;&nbsp;&nbsp;pthread_t tid; <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap, *tsoap; <br />
&nbsp;&nbsp;&nbsp;soap_ssl_init(); /* init OpenSSL (just once) */<br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(CRYPTO_thread_setup()) // OpenSSL <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, "Cannot setup thread mutex\n"); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_ssl_server_context(&amp;soap, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SOAP_SSL_DEFAULT, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"server.pem",	/* keyfile: required when server must authenticate to clients (see SSL docs on how to obtain this file) */ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"password",	/* password to read the key file (not used with GNUTLS) */ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"cacert.pem",	/* optional cacert file to store trusted certificates */ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NULL,		/* optional capath to directory with trusted certificates */ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"dh512.pem",	/* DH file name or DH key len bits (minimum is 512, e.g. "512") to generate DH param, if NULL use RSA */ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NULL,		/* if randfile!=NULL: use a file with random data to seed randomness */  <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NULL		/* optional server identification to enable SSL session cache (must be a unique name) */
&nbsp;&nbsp;&nbsp;)) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;m = soap_bind(&amp;soap, NULL, 18000, 100); // use port 18000 <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(m  &lt;  0) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;fprintf(stderr, "Socket connection successful: master socket = %d<tt>\</tt>n", m); <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(;;) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s = soap_accept(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, "Socket connection successful: slave socket = %d<tt>\</tt>n", s); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(s  &lt;  0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tsoap = soap_copy(&amp;soap); /* should call soap_ssl_accept on a copy */ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!tsoap) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>break</b>; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pthread_create(&amp;tid, NULL, &amp;process_request, (<b>void</b>*)tsoap); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap_done(&amp;soap); /* deallocates SSL context */<br />
&nbsp;&nbsp;&nbsp;CRYPTO_thread_cleanup(); // OpenSSL <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
}  <br />
<b>void</b>&nbsp;*process_request(<b>void</b>&nbsp;*soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;pthread_detach(pthread_self()); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_ssl_accept((<b>struct</b>&nbsp;soap*)soap)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(tsoap, stderr); <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_serve((<b>struct</b>&nbsp;soap*)soap); <br />
&nbsp;&nbsp;&nbsp;soap_destroy((<b>struct</b>&nbsp;soap*)soap); <br />
&nbsp;&nbsp;&nbsp;soap_end((<b>struct</b>&nbsp;soap*)soap); <br />
&nbsp;&nbsp;&nbsp;soap_free((<b>struct</b>&nbsp;soap*)soap); // done and free context <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;NULL; <br />
}
</td></tr></table><br></i>
The <i>soap_ssl_server_context</i> function initializes the server-side SSL context. The <i>server.pem</i> key file is the server's private key concatenated with its certificate. The <i>cacert.pem</i> is used to authenticate clients and contains the client certificates. Alternatively a directory name can be specified. This directory is assumed to contain the certificates. The <i>dh512.pem</i> file specifies that DH will be used for key agreement instead of RSA. A numeric value greater than 512 can be provided instead as a string constant (e.g. <i>"512"</i>) to allow the engine to generate the DH parameters on the fly (this can take a while) rather than retrieving them from a file. The randfile entry can be used to seed the PRNG. The last entry enable server-side session caching. A unique server name is required.

<div class="p"><!----></div>
The GNUTLS mutex lock setup is automatically peformed in the gSOAP engine, but only when POSIX threads are detected and available.

<div class="p"><!----></div>
OpenSSL requires mutex locks to be explicitly setup in your code for multithreaded applications, for which we need to call <i>CRYPTO_thread_setup()</i> and <i>CRYPTO_thread_cleanup()</i>. These routines can be found in <i>openssl/crypto/threads/th-lock.c</i> and are also used in the SSL example codes <i>samples/ssl</i>. These routines are required to setup locks for multi-threaded applications that use SSL.

<div class="p"><!----></div>
We give a Windows and POSIX threads implementation of these here:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include  &lt; unistd.h &gt; 		/* defines _POSIX_THREADS if pthreads are available */ <br />
#ifdef _POSIX_THREADS <br />
# include  &lt; pthread.h &gt;  <br />
#endif <br />
#if defined(WIN32) <br />
# define MUTEX_TYPE             HANDLE <br />
# define MUTEX_SETUP(x)         (x) = CreateMutex(NULL, FALSE, NULL) <br />
# define MUTEX_CLEANUP(x)       CloseHandle(x) <br />
# define MUTEX_LOCK(x)          WaitForSingleObject((x), INFINITE) <br />
# define MUTEX_UNLOCK(x)        ReleaseMutex(x) <br />
# define THREAD_ID              GetCurrentThreadID() <br />
#elif defined(_POSIX_THREADS) <br />
# define MUTEX_TYPE             pthread_mutex_t <br />
# define MUTEX_SETUP(x)         pthread_mutex_init(&amp;(x), NULL) <br />
# define MUTEX_CLEANUP(x)       pthread_mutex_destroy(&amp;(x)) <br />
# define MUTEX_LOCK(x)          pthread_mutex_lock(&amp;(x)) <br />
# define MUTEX_UNLOCK(x)        pthread_mutex_unlock(&amp;(x)) <br />
# define THREAD_ID              pthread_self() <br />
#else <br />
# error "You must define mutex operations appropriate for your platform" <br />
# error "See OpenSSL /threads/th-lock.c on how to implement mutex on your platform" <br />
#endif <br />
<b>struct</b>&nbsp;CRYPTO_dynlock_value { MUTEX_TYPE mutex; }; <br />
<b>static</b>&nbsp;MUTEX_TYPE *mutex_buf; <br />
<b>static</b>&nbsp;<b>struct</b>&nbsp;CRYPTO_dynlock_value *dyn_create_function(<b>const</b>&nbsp;<b>char</b>&nbsp;*file, <b>int</b>&nbsp;line) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;CRYPTO_dynlock_value *value; <br />
&nbsp;&nbsp;&nbsp;value = (<b>struct</b>&nbsp;CRYPTO_dynlock_value*)malloc(<b>sizeof</b>(<b>struct</b>&nbsp;CRYPTO_dynlock_value)); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(value) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MUTEX_SETUP(value<tt>-&gt;</tt>mutex); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;value; <br />
} <br />
<b>static</b>&nbsp;<b>void</b>&nbsp;dyn_lock_function(<b>int</b>&nbsp;mode, <b>struct</b>&nbsp;CRYPTO_dynlock_value *l, <b>const</b>&nbsp;<b>char</b>&nbsp;*file, <b>int</b>&nbsp;line) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(mode &amp; CRYPTO_LOCK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MUTEX_LOCK(l<tt>-&gt;</tt>mutex); <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MUTEX_UNLOCK(l<tt>-&gt;</tt>mutex); <br />
} <br />
<b>static</b>&nbsp;<b>void</b>&nbsp;dyn_destroy_function(<b>struct</b>&nbsp;CRYPTO_dynlock_value *l, <b>const</b>&nbsp;<b>char</b>&nbsp;*file, <b>int</b>&nbsp;line) <br />
{ <br />
&nbsp;&nbsp;&nbsp;MUTEX_CLEANUP(l<tt>-</tt>&#62;mutex); <br />
&nbsp;&nbsp;&nbsp;free(l); <br />
} <br />
<b>void</b>&nbsp;locking_function(<b>int</b>&nbsp;mode, <b>int</b>&nbsp;n, <b>const</b>&nbsp;<b>char</b>&nbsp;*file, <b>int</b>&nbsp;line) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(mode &amp; CRYPTO_LOCK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MUTEX_LOCK(mutex_buf[n]); <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MUTEX_UNLOCK(mutex_buf[n]); <br />
} <br />
<b>unsigned</b>&nbsp;<b>long</b>&nbsp;id_function() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;(<b>unsigned</b>&nbsp;<b>long</b>)THREAD_ID; <br />
} <br />
<b>int</b>&nbsp;CRYPTO_thread_setup() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;i; <br />
&nbsp;&nbsp;&nbsp;mutex_buf = (MUTEX_TYPE*)malloc(CRYPTO_num_locks() * sizeof(MUTEX_TYPE)); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!mutex_buf) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_EOM; <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  CRYPTO_num_locks(); i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MUTEX_SETUP(mutex_buf[i]); <br />
&nbsp;&nbsp;&nbsp;CRYPTO_set_id_callback(id_function); <br />
&nbsp;&nbsp;&nbsp;CRYPTO_set_locking_callback(locking_function); <br />
&nbsp;&nbsp;&nbsp;CRYPTO_set_dynlock_create_callback(dyn_create_function); <br />
&nbsp;&nbsp;&nbsp;CRYPTO_set_dynlock_lock_callback(dyn_lock_function); <br />
&nbsp;&nbsp;&nbsp;CRYPTO_set_dynlock_destroy_callback(dyn_destroy_function); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
<b>void</b>&nbsp;CRYPTO_thread_cleanup() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;i; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!mutex_buf) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>; <br />
&nbsp;&nbsp;&nbsp;CRYPTO_set_id_callback(NULL); <br />
&nbsp;&nbsp;&nbsp;CRYPTO_set_locking_callback(NULL); <br />
&nbsp;&nbsp;&nbsp;CRYPTO_set_dynlock_create_callback(NULL); <br />
&nbsp;&nbsp;&nbsp;CRYPTO_set_dynlock_lock_callback(NULL); <br />
&nbsp;&nbsp;&nbsp;CRYPTO_set_dynlock_destroy_callback(NULL); <br />
&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(i = 0; i  &lt;  CRYPTO_num_locks(); i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;MUTEX_CLEANUP(mutex_buf[i]); <br />
&nbsp;&nbsp;&nbsp;free(mutex_buf); <br />
&nbsp;&nbsp;&nbsp;mutex_buf = NULL; <br />
}
</td></tr></table><br></i>
For Unix and Linux, make sure you have signal handlers set in your service and/or client applications to catch broken connections (<i>SIGPIPE</i>):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
signal(SIGPIPE, sigpipe_handle);
</td></tr></table><br></i>
where, for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>void</b>&nbsp;sigpipe_handle(<b>int</b>&nbsp;x) { }
</td></tr></table><br></i>
By default, clients are not required to authenticate. To support client authentication use the following:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_ssl_server_context(&amp;soap, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"server.pem", <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"password", <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"cacert.pem", <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NULL, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"dh512.pem", <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NULL, <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NULL <br />
&nbsp;&nbsp;&nbsp;)) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;}
</td></tr></table><br></i>
This requires each client to authenticate with its certificate.

<div class="p"><!----></div>
Since release version 2.8.20 SSL v3 is disabled. To enable SSL v3 together with TLS v1 use <i>SOAP_SSLv3_TLSv1</i> in <i>soap_ssl_server_context</i>.

<div class="p"><!----></div>
The <i>cacert</i> file and <i>capath</i> are optional. Either one can be
specified when clients must run on non-trusted systems (<i>capath</i> is not used with GNUTLS). We want to avoid
storing trusted certificates in the default location on the file system when
that is not secure. Therefore, a flat <i>cacert.pem</i> file or directory can be
specified to store trusted certificates.

<div class="p"><!----></div>
The gSOAP distribution includes a <i>cacerts.pem</i> file with the certificates
of all certificate authorities such as Verisign. You can use this file to
verify the authentication of servers that provide certificates issued by these
CAs.

<div class="p"><!----></div>
The <i>cacert.pem</i>, <i>client.pem</i>, and <i>server.pem</i> files in the gSOAP
distribution are examples of self-signed certificates.
The <i>client.pem</i> and <i>server.pem</i> contain the client/server private key
concatenated with the certificate. The keyfiles (<i>client.pem</i> and
<i>server.pem</i>) are created by concatenating the private key PEM with the
certificate PEM. The keyfile SHOULD NEVER be shared with any party. With
OpenSSL, you can encrypt the keyfiles with a password to offer some protection
and the password is used in the client/server code to read the keyfile. GNUTLS
does not support this feature and cannot encrypt or decrypt a keyfile.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: it is important that the <i>WITH_OPENSSL</i> macro MUST be consistently defined to
compile the sources, such as <i>stdsoap2.cpp</i>, <i>soapC.cpp</i>,
<i>soapClient.cpp</i>, <i>soapServer.cpp</i>, and all application sources that
include <i>stdsoap2.h</i> or <i>soapH.h</i>. If the macros are not consistently
used, the application will crash due to a mismatches in the declaration and
access of the gSOAP context.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.22">
19.22</a>&nbsp;&nbsp;<font color="#0000FF">Secure Clients with HTTPS/SSL</font></h3><a name="sec:clientopenssl">
</a>

<div class="p"><!----></div>
To utilize HTTPS/SSL, you need to install the OpenSSL library on your platform or GNUTLS for a light-weight SSL/TLS library.
After installation, compile all the sources of your application with option <i>-DWITH_OPENSSL</i> (or <i>-DWITH_GNUTLS</i> when using GNUTLS). For example on Linux:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -DWITH_OPENSSL myclient.cpp stdsoap.cpp soapC.cpp soapClient.cpp -lssl -lcrypto</i>
</td></tr></table><br></span>
or Unix:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -DWITH_OPENSSL myclient.cpp stdsoap.cpp soapC.cpp soapClient.cpp -lxnet -lsocket -lnsl -lssl -lcrypto</i>
</td></tr></table><br></span>
or you can add the following line to <i>soapdefs.h</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#define WITH_OPENSSL
</td></tr></table><br></i>
and compile with option <i>-DWITH_SOAPDEFS_H</i> to include <i>soapdefs.h</i> in your project.
A client program simply uses the prefix <i>https:</i> instead of <i>http:</i> in the endpoint URL of a service operation call to a
Web Service to use encrypted transfers (if the service supports HTTPS). You need to specify the client-side key file and password of the keyfile:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_ssl_init(); /* init OpenSSL (just once) */<br />
<b>if</b>&nbsp;(soap_ssl_client_context(&amp;soap, <br />
&nbsp;&nbsp;&nbsp;SOAP_SSL_DEFAULT, <br />
&nbsp;&nbsp;&nbsp;"client.pem",	/* keyfile: required only when client must authenticate to server (see SSL docs on how to obtain this file) */ <br />
&nbsp;&nbsp;&nbsp;"password",		/* password to read the key file (not used with GNUTLS) */ <br />
&nbsp;&nbsp;&nbsp;"cacerts.pem", 	/* cacert file to store trusted certificates (needed to verify server) */
&nbsp;&nbsp;&nbsp;NULL,		/* capath to directory with trusted certificates */ <br />
&nbsp;&nbsp;&nbsp;NULL		/* if randfile!=NULL: use a file with random data to seed randomness */  <br />
)) <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;exit(1); <br />
} <br />
soap_call_ns__mymethod(&amp;soap, "https://domain/path/secure.cgi", "", ...);
</td></tr></table><br></i>

<div class="p"><!----></div>
By default, server authentication is enabled and the <i>cacerts.pem</i> or
<i>capath</i> (not used with GNUTLS) must be set so that the CA certificates of the server(s) are
accessible at run time. The <i>cacerts.pem</i> file included in the package
contains the certificates of common CAs. This file must be supplied with the
client, if server authentication is required. Althernatively, you can use the
<i>plugin/cacerts.h</i> and <i>plugin/cacerts.c</i> code to embed CA certificates
in your client code.

<div class="p"><!----></div>
Other client-side SSL options are <i>SOAP_SSL_SKIP_HOST_CHECK</i> to skip the host name verification check and <i>SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE</i> to allow connecting to a host with an expired certificate. For example,

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_ssl_init(); /* init OpenSSL (just once) */<br />
<b>if</b>&nbsp;(soap_ssl_client_context(&amp;soap, <br />
&nbsp;&nbsp;&nbsp;SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION  <br />
&nbsp;&nbsp;&nbsp; -  SOAP_SSL_SKIP_HOST_CHECK, <br />
&nbsp;&nbsp;&nbsp; -  SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE, <br />
&nbsp;&nbsp;&nbsp;"client.pem",	/* keyfile: required only when client must authenticate to server (see SSL docs on how to obtain this file) */ <br />
&nbsp;&nbsp;&nbsp;"password",		/* password to read the key file (not used with GNUTLS) */ <br />
&nbsp;&nbsp;&nbsp;"cacerts.pem", 	/* cacert file to store trusted certificates (needed to verify server) */
&nbsp;&nbsp;&nbsp;NULL,		/* capath to directory with trusted certificates */ <br />
&nbsp;&nbsp;&nbsp;NULL		/* if randfile!=NULL: use a file with random data to seed randomness */  <br />
)) <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;exit(1); <br />
} <br />
soap_call_ns__mymethod(&amp;soap, "https://domain/path/secure.cgi", "", ...);
</td></tr></table><br></i>
For systems based on Microsoft windows, the WinInet module can be used instead, see <i>mod_gsoap/gsoap_win/wininet</i>.

<div class="p"><!----></div>
Since release version 2.8.20 SSL v3 is disabled. To enable SSL v3 together with TLS v1 use <i>SOAP_SSLv3_TLSv1</i> in <i>soap_ssl_client_context</i>.

<div class="p"><!----></div>
To disable server authentication for testing purposes, use the following:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>if</b>&nbsp;(soap_ssl_client_context(&amp;soap, <br />
&nbsp;&nbsp;&nbsp;SOAP_SSL_NO_AUTHENTICATION, <br />
&nbsp;&nbsp;&nbsp;NULL, <br />
&nbsp;&nbsp;&nbsp;NULL, <br />
&nbsp;&nbsp;&nbsp;NULL, <br />
&nbsp;&nbsp;&nbsp;NULL, <br />
&nbsp;&nbsp;&nbsp;NULL	<br />
)) <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;exit(1); <br />
} <br />
</td></tr></table><br></i>
This also assumes that the server does not require clients to authenticate (the keyfile is absent).

<div class="p"><!----></div>
Make sure you have signal handlers set in your application to catch broken connections (<i>SIGPIPE</i>):
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
signal(SIGPIPE, sigpipe_handle);
</td></tr></table><br></i>
where, for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>void</b>&nbsp;sigpipe_handle(<b>int</b>&nbsp;x) { }
</td></tr></table><br></i>
<font color="#FF0000"><b>Caution</b></font>: it is important that the <i>WITH_OPENSSL</i> macro MUST be consistently defined to
compile the sources, such as <i>stdsoap2.cpp</i>, <i>soapC.cpp</i>,
<i>soapClient.cpp</i>, <i>soapServer.cpp</i>, and all application sources that
include <i>stdsoap2.h</i> or <i>soapH.h</i>. If the macros are not consistently
used, the application will crash due to a mismatches in the declaration and
access of the gSOAP context.
<font color="#FF0000"><b>Caution</b></font>: concurrent client calls MUST be made using separate soap structs copied with <i>soap_copy</i> from an originating struct initialized with <i>soap_ssl_client_context</i>. In addition, the thread initialization code discussed in Section&nbsp;<a href="#sec:serveropenssl">19.21</a> MUST be used to properly setup OpenSSL in a multi-threaded client application.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.23">
19.23</a>&nbsp;&nbsp;<font color="#0000FF">SSL Authentication Callbacks</font></h3>

<div class="p"><!----></div>
The <i>fsslauth</i> callback function controls OpenSSL/GNUTLS authentication initialization:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Callback (function pointer)</b></font> </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fsslauth)(<b>struct</b>&nbsp;soap *soap)</i> </td></tr>
<tr><td align="left">Initialize the authentication information for clients and services, such as the
certificate chain, password, read the key and/or DH file, generate an RSA key,
and initialization of the RNG.  Should return a gSOAP error code or
<i>SOAP_OK</i>.  Built-in gSOAP function: <i>ssl_auth_init</i>
</td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
The <i>fsslverify</i> callback function controls OpenSSL peer certificate
verification, via internally invoking <i>SSL_CTX_set_verify</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Callback (function pointer)</b></font> </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;(*soap.fssverify)(<b>int</b>&nbsp;ok, X509_STORE_CTX *store</i> </td></tr>
<tr><td align="left">Used to control the certificate verification behaviour when the
<i>SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION</i> or
<i>SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION</i> flags are specified with
<i>soap_ssl_client_context</i> and <i>soap_ssl_server_context</i>. It
receives two arguments: <i>ok</i> indicates, whether the verification of the
certificate in question was passed (<i>ok=1</i>) or not (]blkok=0).  If the
callback returns 0, the verification process is immediately stopped with
"verification failed" state. A verification failure alert is sent to the peer
and the TLS/SSL handshake is terminated. If the callback returns 1, the
verification process is continued.  Built-in gSOAP function:
<i>ssl_verify_callback</i> and
<i>ssl_verify_callback_allow_expired_certificate</i>. These functions are
used when <i>fsslverify</i> is initially set to <i>NULL</i> and were not
reassigned before <i>soap_ssl_client_context</i> or
<i>soap_ssl_server_context</i> are called.
</td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.24">
19.24</a>&nbsp;&nbsp;<font color="#0000FF">SSL Certificates and Key Files</font></h3><a name="sec:ssl">
</a>

<div class="p"><!----></div>
The gSOAP distribution includes a <i>cacerts.pem</i> file with the certificates
of all certificate authorities (such as Verisign). You can use this file to
verify the authentication of servers that provide certificates issued by these
CAs. Just set the <i>cafile</i> parameter to the location of this file on your
file system.  Therefore, when you obtain a certifice signed by a trusted CA
such as Verisign, you can simply use the <i>cacerts.pem</i> file to develop
client applications that can verify the authenticity of your server.

<div class="p"><!----></div>
Althernatively, you can use the <i>plugin/cacerts.h</i> and
<i>plugin/cacerts.c</i> code to embed CA certificates in your client code.

<div class="p"><!----></div>
For systems based on Microsoft windows, the WinInet module can be used instead,
see the <i>README.txt</i> located in the package under
<i>mod_gsoap/gsoap_win/wininet</i>.

<div class="p"><!----></div>
The other <i>.pem</i> files in the gSOAP distribution are examples
of self-signed certificates for testing purposes (<i>cacert.pem</i>, <i>client.pem</i>, <i>server.pem</i>). The <i>client.pem</i> and <i>server.pem</i> contain the private key and certificate of the client or server, respectively. The keyfiles (<i>client.pem</i> and <i>server.pem</i>) are created by concatenating the private key PEM with the certificate PEM. The keyfile SHOULD NEVER be shared with any party. With OpenSSL, you can encrypt the keyfiles with a password to offer some protection and the password is used in the client/server code to read the keyfile. GNUTLS does not support this feature and cannot encrypt or decrypt a keyfile.

<div class="p"><!----></div>
You can also create your own self-signed certificates.  There is more than one
way to generate the necessary files for clients and servers.
See <i>http://www.openssl.org</i> for information on OpenSSL and
<i>http://sial.org/howto/openssl/ca/</i> on how to setup and manage a local CA
and <i>http://sial.org/howto/openssl/self-signed/</i> on how to setup self-signed
test certificates.

<div class="p"><!----></div>
It is possible to convert IIS-generated certificates to PEM format with the openssl library and openssl command-line tool:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
openssl x509 -in mycert.cer -inform DER -out mycert.pem -outform PEM
</td></tr></table><br></i>
This converts the CRT-formatted mycert.cer to PEM-formatted mycert.pem.

<div class="p"><!----></div>
Here is the simplest way to setup self-signed certificates. First you need to create a private Certificate Authority (CA).  The CA is used in SSL to verify the authenticity of a given
certificate. The CA acts as a trusted third party who has authenticated the
user of the signed certificate as being who they say. The certificate is
signed by the CA, and if the client trusts the CA, it will trust your
certificate. For use within your organization, a private CA will probably
serve your needs. However, if you intend use your certificates for a public
service, you should probably obtain a certificate from a known CA (e.g.&nbsp;VeriSign).
In addition to identification, your certificate is also used for encryption.

<div class="p"><!----></div>
Creating certificates should be done through a CA to obtain signed certificates. But you can create your own certificates for testing purposes as follows.

<ul>
<li> Go to the OpenSSL bin directory (<i>/usr/local/ssl</i> by default and
<i>/System/Library/OpenSSL</i> on Mac OS X)
<div class="p"><!----></div>
</li>

<li> There should be a file called openssl.cnf
<div class="p"><!----></div>
</li>

<li> Create a new directory in your home account, e.g. $HOME/CA, and copy the openssl.cnf file to this directory
<div class="p"><!----></div>
</li>

<li> Modify openssl.cnf by changing the 'dir' value to HOME/CA
<div class="p"><!----></div>
</li>

<li> Copy the README.txt, root.sh, and cert.sh scripts from the gSOAP distribution package located in the samples/ssl directory to HOME/CA
<div class="p"><!----></div>
</li>

<li> Follow the README.txt instructions
<div class="p"><!----></div>
</li>
</ul>
You now have a self-signed CA root certificate cacert.pem and a server.pem (or client.pem) certificate in PEM format.
The cacert.pem certificate is used in the <i>cafile</i> parameter of the <i>soap_ssl_client_context</i> (or <i>soap_ssl_server_context</i>) at the client (or server) side to verify the authenticity of the peer. You can also provide a capath parameter to these trusted certificates. The server.pem (or client.pem) must be provided with the <i>soap_ssl_server_context</i> at the server side (or <i>soap_ssl_client_context</i> at the client side) together with the password you entered when generating the certificate using cert.sh to access the file. These certificates must be present to grant authentication requests by peers. In addition, the server.pem (and client.pem) include the host name of the machine on which the application runs (e.g. localhost), so you need to generate new certificates when migrating a server (or client).

<div class="p"><!----></div>
Finally, you need to generate Diffie-Helmann (DH) parameters for the server if
you wish to use DH instead of RSA. There are two options:

<ol type="1">
<li> Set the <i>dhfile</i> parameter to the numeric DH prime length in bits
required (for example "1024") to let the engine generate DH parameters at
initialization. This can be time consuming.
<div class="p"><!----></div>
</li>

<li> Provide a file name for the <i>dhfile</i> parameter of
<i>soap_ssl_server_context</i>. The file should be generated beforehand. To
do so with the OpenSSL command line tool, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
 &gt;  <i>openssl dhparam -outform PEM -out dh.pem 512</i>
</td></tr></table><br></span>
File <i>dh512.pem</i> is the output file and 512 is the number of bits used.
<div class="p"><!----></div>
</li>
</ol>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.25">
19.25</a>&nbsp;&nbsp;<font color="#0000FF">SSL Hardware Acceleration</font></h3>

<div class="p"><!----></div>
You can specify a hardware engine to enable hardware support for cryptographic acceleration. This can be done once in a server or client with the following statements:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>static</b>&nbsp;<b>const</b>&nbsp;<b>char</b>&nbsp;*engine = "cswift"; /* engine name */ <br />
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;ENGINE *e; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!(e = ENGINE_by_id(engine))) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, "Error finding engine %s\n", engine); <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<b>if</b>&nbsp;(!ENGINE_set_default(e, ENGINE_METHOD_ALL)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, "Error using engine %s\n", engine); <br />
&nbsp;&nbsp;&nbsp;...
</td></tr></table><br></i>
The following table lists the names of the hardware and software engines:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Name</b></font> </td><td align="left"><font color="#FF0000"><b>Description</b></font> </td></tr>
<tr><td align="left">openssl	</td><td align="left">The default software engine for cryptographic operations </td></tr>
<tr><td align="left">openbsd_dev_crypto	</td><td align="left">OpenBSD supports kernel level cryptography </td></tr>
<tr><td align="left">cswift		</td><td align="left">CryptoSwift acceleration hardware </td></tr>
<tr><td align="left">chil		</td><td align="left">nCipher CHIL acceleration hardware </td></tr>
<tr><td align="left">atalla		</td><td align="left">Compaq Atalla acceleration hardware </td></tr>
<tr><td align="left">nuron		</td><td align="left">Nuron acceleration hardware </td></tr>
<tr><td align="left">ubsec		</td><td align="left">Broadcom uBSec acceleration hardware </td></tr>
<tr><td align="left">aep		</td><td align="left">Aep acceleration hardware </td></tr>
<tr><td align="left">sureware	</td><td align="left">SureWare acceleration hardware </td></tr></table>

</td></tr></table><br></span>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.26">
19.26</a>&nbsp;&nbsp;<font color="#0000FF">SSL on Windows</font></h3>

<div class="p"><!----></div>
Set the full path to libssl.lib and libcrypto.lib 
under the MSVC++ "Projects" menu, then choose "Link": "Object/Modules".
Please make sure <i>libssl32.dll</i> and <i>libeay32.dll</i> can be loaded by
gSOAP applications, thus they must be installed properly on the target
machine.

<div class="p"><!----></div>
If you're using compilation settings such as <i>/MTd</i> then link to the correct <i>libeay32MTd.lib</i> and <i>ssleay32MTd.lib</i> libraries.

<div class="p"><!----></div>
Alternatively, you can use the WinInet interface available in the <i>mod_gsoap</i> directory of the gSOAP package. API instructions are included in the source.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.27">
19.27</a>&nbsp;&nbsp;<font color="#0000FF">Zlib Compression</font></h3><a name="sec:compression">
</a>

<div class="p"><!----></div>
To enable deflate and gzip compression with Zlib, install Zlib from
<tt>http://www.zlib.org</tt> if not already installed on your system.  Compile
<i>stdsoap2.cpp</i> (or <i>stdsoap2.c</i>) and <b>all</b> your sources that include
<i>stdsoap2.h</i> or <i>soapH.h</i> with compiler option <i>-DWITH_GZIP</i> and
link your code with the Zlib library, e.g. <i>-lz</i> on Unix/Linux platforms.

<div class="p"><!----></div>
The gzip compression is orthogonal to all transport encodings such as HTTP,
SSL, DIME, and can be used with other transport layers.  You can even save and
load compressed XML data to/from files.

<div class="p"><!----></div>
gSOAP supports two compression formats: deflate and gzip. The gzip format is
used by default. The gzip format has several benefits over deflate. Firstly,
gSOAP can automatically detect gzip compressed inbound messages, even without
HTTP headers, by checking for the presence of a gzip header in the message
content. Secondly, gzip includes a CRC32 checksum to ensure messages have been
correctly received. Thirdly, gzip compressed content can be decompressed with
other compression software, so you can decompress XML data saved by gSOAP in
gzip format.

<div class="p"><!----></div>
Gzip compression is enabled by compiling the sources with <i>-DWITH_GZIP</i>.
To transmit gzip compressed SOAP/XML data, set the output mode flags to
<i>SOAP_ENC_ZLIB</i>. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_init(&amp;soap); <br />
... <br />
soap_set_omode(&amp;soap, SOAP_ENC_ZLIB); // enable Zlib's gzip <br />
<b>if</b>&nbsp;(soap_call_ns__myMethod(&amp;soap, ...)) <br />
... <br />
soap_clr_omode(&amp;soap, SOAP_ENC_ZLIB); // disable Zlib's gzip <br />
...
</td></tr></table><br></i>
This will send a compressed SOAP/XML request to a service, provided that Zlib is
installed and linked with the application and the <i>-DWITH_GZIP</i> option was used to compile the sources.
Receiving compressed SOAP/XML over HTTP either in gzip or deflate formats is automatic. The <i>SOAP_ENC_ZLIB</i> flag does not have
to be set at the server side to accept compressed messages. Reading and receiving gzip compressed SOAP/XML without HTTP headers (e.g. with other transport protocols) is also automatic.

<div class="p"><!----></div>
To control the level of compression for outbound messages, you can set the <i>soap.z_level</i> to a value between 1 and 9, where 1 is the best speed and 9 is the best compression (default is 6).  For example
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_init(&amp;soap); <br />
... <br />
soap_set_omode(&amp;soap, SOAP_ENC_ZLIB); <br />
soap.z_level = 9; // best compression <br />
...
</td></tr></table><br></i>
To verify and monitor compression rates, you can use the values <i>soap.z_ratio_in</i> and <i>soap.z_ratio_out</i>. These two float values lie between 0.0 and 1.0 and express the ratio of the compressed message length over uncompressed message length.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_call_ns__myMethod(&amp;soap, ...); <br />
... <br />
printf("Compression ratio: %f%% (in) %f%% (out)\n", 100*soap.z_ratio_out, 100*soap.z_ratio_in); <br />
...
</td></tr></table><br></i>
Note: lower ratios mean higher compression rates.

<div class="p"><!----></div>
Compressed transfers require buffering the entire output message to determine HTTP message length.
This means that the <i>SOAP_IO_STORE</i> flag is
automatically set when the <i>SOAP_ENC_ZLIB</i> flag is set to send compressed messages. The use of HTTP chunking
significantly reduces memory usage and may speed up the transmission of compressed SOAP/XML messages.
This is accomplished by setting the <i>SOAP_IO_CHUNK</i> flag with
<i>SOAP_ENC_ZLIB</i> for the output mode.
However, some Web servers do not accept HTTP chunked request messages (even when they return HTTP chunked messages!). Stand-alone gSOAP services always accept chunked request messages.

<div class="p"><!----></div>
To restrict the compression to the deflate format only, compile the sources with <i>-DWITH_ZLIB</i>. This limits compression and decompression to the deflate format. Only plain and deflated messages can be exchanged, gzip is not supported with this option.
Receiving gzip compressed content is automatic, even in the absence of HTTP headers.
Receiving deflate compressed content is not automatic in the absence of HTTP headers and requires the flag
<i>SOAP_ENC_ZLIB</i> to be set for the input mode to decompress deflated data.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: it is important that the <i>WITH_GZIP</i> and <i>WITH_ZLIB</i> macros MUST be consistently defined to
compile the sources, such as <i>stdsoap2.cpp</i>, <i>soapC.cpp</i>,
<i>soapClient.cpp</i>, <i>soapServer.cpp</i>, and all application sources that
include <i>stdsoap2.h</i> or <i>soapH.h</i>. If the macros are not consistently
used, the application will crash due to a mismatches in the declaration and
access of the gSOAP context.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.28">
19.28</a>&nbsp;&nbsp;<font color="#0000FF">Client-Side Cookie Support</font></h3><a name="sec:clientcookie">
</a>

<div class="p"><!----></div>
Client-side cookie support is optional. To enable cookie support, compile all sources with option <i>-DWITH_COOKIES</i>, for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -DWITH_COOKIES -o myclient stdsoap2.cpp soapC.cpp soapClient.cpp</i>
</td></tr></table><br></span>
or add the following line to <i>stdsoap.h</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#define WITH_COOKIES
</td></tr></table><br></i>
Client-side cookie support is fully automatic. So just (re)compile <i>stdsoap2.cpp</i> with <i>-DWITH_COOKIES</i> to enable
cookie-based session control in your client.

<div class="p"><!----></div>
A database of cookies is kept and returned to the appropriate servers.
Cookies are not automatically saved to a file by a client. An example cookie
file manager is included as an extras in the distribution. You should
explicitly remove all cookies before terminating a gSOAP context by
calling <i>soap_free_cookies(soap)</i> or by calling <i>soap_done(soap)</i>.

<div class="p"><!----></div>
To avoid "cookie storms" caused by malicious servers that return an 
unreasonable amount of cookies, gSOAP clients/servers are restricted to
a database size that the user can limit (32 cookies by default), for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
soap.cookie_max = 10;
</td></tr></table><br></i>
The cookie database is a linked list pointed to by <i>soap.cookies</i> where each node is declared as:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap_cookie <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*name; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*value; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*domain; <br />
&nbsp;&nbsp;&nbsp;<b>char</b>&nbsp;*path; <br />
&nbsp;&nbsp;&nbsp;<b>long</b>&nbsp;expire; /* client-side: local time to expire; server-side: seconds to expire */ <br />
&nbsp;&nbsp;&nbsp;<b>unsigned</b>&nbsp;<b>int</b>&nbsp;version; <br />
&nbsp;&nbsp;&nbsp;<b>short</b>&nbsp;secure; <br />
&nbsp;&nbsp;&nbsp;<b>short</b>&nbsp;session; /* server-side */ <br />
&nbsp;&nbsp;&nbsp;<b>short</b>&nbsp;env; /* server-side: 1 = got cookie from client */ <br />
&nbsp;&nbsp;&nbsp;<b>short</b>&nbsp;modified; /* server-side: 1 = client cookie was modified */ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap_cookie *next; <br />
};
</td></tr></table><br></i>
Since the cookie database is linked to a <i>soap</i> struct, each thread has a local cookie database in a multi-threaded
implementation.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.29">
19.29</a>&nbsp;&nbsp;<font color="#0000FF">Server-Side Cookie Support</font></h3><a name="sec:servercookie">
</a>

<div class="p"><!----></div>
Server-side cookie support is optional. To enable cookie support, compile all sources with option <i>-DWITH_COOKIES</i>, for example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -DWITH_COOKIES -o myserver ...</i>
</td></tr></table><br></span>
gSOAP provides the following cookie API for server-side cookie session control:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Function</b></font> </td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap_cookie *soap_set_cookie(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*name, <b>const</b>&nbsp;<b>char</b>&nbsp;*value, <b>const</b>&nbsp;<b>char</b>&nbsp;*domain, <b>const</b>&nbsp;<b>char</b>&nbsp;*path);</i> </td></tr>
<tr><td align="left">Add a cookie to the database with name <i>name</i> and value <i>value</i>.
<i>domain</i> and <i>path</i> may be NULL to use the current domain and path given by <i>soap_cookie_domain</i> and <i>soap_cookie_path</i>.
If successful, returns pointer to a cookie node in the linked list, or NULL otherwise.
</td></tr>
<tr><td align="left"><i><b>struct</b>&nbsp;soap_cookie *soap_cookie(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*name, <b>const</b>&nbsp;<b>char</b>&nbsp;*domain, <b>const</b>&nbsp;<b>char</b>&nbsp;*path);</i> </td></tr>
<tr><td align="left">Find a cookie in the database with name <i>name</i> and value <i>value</i>.
<i>domain</i> and <i>path</i> may be NULL to use the current domain and path given by <i>soap_cookie_domain</i> and <i>soap_cookie_path</i>.
If successful, returns pointer to a cookie node in the linked list, or NULL otherwise.
</td></tr>
<tr><td align="left"><i><b>char</b>&nbsp;*soap_cookie_value(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*name, <b>const</b>&nbsp;<b>char</b>&nbsp;*domain, <b>const</b>&nbsp;<b>char</b>&nbsp;*path);</i> </td></tr>
<tr><td align="left">Get value of a cookie in the database with name <i>name</i>.
<i>domain</i> and <i>path</i> may be NULL to use the current domain and path given by <i>soap_cookie_domain</i> and <i>soap_cookie_path</i>.
If successful, returns the string pointer to the value, or NULL otherwise.
</td></tr>
<tr><td align="left"><i><b>long</b>&nbsp;soap_cookie_expire(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*name, <b>const</b>&nbsp;<b>char</b>&nbsp;*domain, <b>const</b>&nbsp;<b>char</b>&nbsp;*path);</i> </td></tr>
<tr><td align="left">Get expiration value of the cookie in the database with name <i>name</i> (in seconds).
<i>domain</i> and <i>path</i> may be NULL to use the current domain and path given by <i>soap_cookie_domain</i> and <i>soap_cookie_path</i>.
Returns the expiration value, or -1 if cookie does not exist.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap_set_cookie_expire(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*name, <b>long</b>&nbsp;expire, <b>const</b>&nbsp;<b>char</b>&nbsp;*domain, <b>const</b>&nbsp;<b>char</b>&nbsp;*path);</i> </td></tr>
<tr><td align="left">Set expiration value <i>expire</i> of the cookie in the database with name <i>name</i> (in seconds).
<i>domain</i> and <i>path</i> may be NULL to use the current domain and path given by <i>soap_cookie_domain</i> and <i>soap_cookie_path</i>.
If successful, returns <i>SOAP_OK</i>, or <i>SOAP_EOF</i> otherwise.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap_set_cookie_session(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*name, <b>const</b>&nbsp;<b>char</b>&nbsp;*domain, <b>const</b>&nbsp;<b>char</b>&nbsp;*path);</i> </td></tr>
<tr><td align="left">Set cookie in the database with name <i>name</i> to be a session cookie.
This means that the cookie will be returned to the client.
(Only cookies that are modified are returned to the client).
<i>domain</i> and <i>path</i> may be NULL to use the current domain and path given by <i>soap_cookie_domain</i> and <i>soap_cookie_path</i>.
If successful, returns <i>SOAP_OK</i>, or <i>SOAP_EOF</i> otherwise.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap_clr_cookie_session(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*name, <b>const</b>&nbsp;<b>char</b>&nbsp;*domain, <b>const</b>&nbsp;<b>char</b>&nbsp;*path);</i> </td></tr>
<tr><td align="left">Clear cookie in the database with name <i>name</i> to be a session cookie.
<i>domain</i> and <i>path</i> may be NULL to use the current domain and path given by <i>soap_cookie_domain</i> and <i>soap_cookie_path</i>.
If successful, returns <i>SOAP_OK</i>, or <i>SOAP_EOF</i> otherwise.
</td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;soap_clr_cookie(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*name, <b>const</b>&nbsp;<b>char</b>&nbsp;*domain, <b>const</b>&nbsp;<b>char</b>&nbsp;*path);</i> </td></tr>
<tr><td align="left">Remove cookie from the database with name <i>name</i>.
<i>domain</i> and <i>path</i> may be NULL to use the current domain and path given by <i>soap_cookie_domain</i> and <i>soap_cookie_path</i>.
</td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;soap_getenv_cookies(<b>struct</b>&nbsp;soap *soap);</i> </td></tr>
<tr><td align="left">Initializes cookie database by reading the 'HTTP_COOKIE' environment variable.
This provides a means for a CGI application to read cookies send by a client.
If successful, returns <i>SOAP_OK</i>, or <i>SOAP_EOF</i> otherwise.
</td></tr>
<tr><td align="left"><i><b>void</b>&nbsp;soap_free_cookies(<b>struct</b>&nbsp;soap *soap);</i> </td></tr>
<tr><td align="left">Release cookie database. </td></tr></table>

</td></tr></table><br></span>
The following global variables are used to define the current domain and path:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><font color="#FF0000"><b>Attribute</b></font> </td><td align="left"><font color="#FF0000"><b>value</b></font> </td></tr>
<tr><td align="left"><i><b>const</b>&nbsp;<b>char</b>&nbsp;*cookie_domain</i> </td><td align="left">MUST be set to the domain (host) of the service </td></tr>
<tr><td align="left"><i><b>const</b>&nbsp;<b>char</b>&nbsp;*cookie_path</i> </td><td align="left">MAY be set to the default path to the service </td></tr>
<tr><td align="left"><i><b>int</b>&nbsp;cookie_max</i> </td><td align="left">maximum cookie database size (default=32) </td></tr></table>

</td></tr></table><br></span>
The <i>cookie_path</i> value is used to filter cookies intended for this service according to the path prefix rules outlined in
RFC2109.

<div class="p"><!----></div>
The following example server adopts cookies for session control:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;main() <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;m, s; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap.cookie_domain = "..."; <br />
&nbsp;&nbsp;&nbsp;soap.cookie_path = "/"; // the path which is used to filter/set cookies with this destination <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(argc  &lt;  2) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_getenv_cookies(&amp;soap); // CGI app: grab cookies from 'HTTP_COOKIE' env var <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_serve(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;m = soap_bind(&amp;soap, NULL, atoi(argv[1]), 100); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(m  &lt;  0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>for</b>&nbsp;(<b>int</b>&nbsp;i = 1; ; i++) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s = soap_accept(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(s  &lt;  0) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(1); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_serve(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_end(&amp;soap);		// clean up  <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_free_cookies(&amp;soap);	// remove all old cookies from database so no interference occurs with the arrival of new cookies <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
} <br />
<b>int</b>&nbsp;ck__demo(<b>struct</b>&nbsp;soap *soap, ...) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;n; <br />
&nbsp;&nbsp;&nbsp;<b>const</b>&nbsp;<b>char</b>&nbsp;*s; <br />
&nbsp;&nbsp;&nbsp;s = soap_cookie_value(soap, "demo", NULL, NULL); // cookie returned by client? <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!s) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;s = "init-value"; // no: set initial cookie value <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... // modify 's' to reflect session control <br />
&nbsp;&nbsp;&nbsp;soap_set_cookie(soap, "demo", s, NULL, NULL); <br />
&nbsp;&nbsp;&nbsp;soap_set_cookie_expire(soap, "demo", 5, NULL, NULL); // cookie may expire at client-side in 5 seconds <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.30">
19.30</a>&nbsp;&nbsp;<font color="#0000FF">Connecting Clients Through Proxy Servers</font></h3>

<div class="p"><!----></div>
When a client needs to connect to a Web Service through a proxy server, set the <i>soap.proxy_host</i> string and
<i>soap.proxy_port</i> integer attributes of the current <i>soap</i> runtime context to the proxy's host name and port, respectively. For example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
soap.proxy_host = "proxyhostname"; <br />
soap.proxy_port = 8080; <br />
<b>if</b>&nbsp;(soap_call_ns__method(&amp;soap, "http://host:port/path", "action", ...)) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
<b>else</b><br />
&nbsp;&nbsp;&nbsp;...
</td></tr></table><br></i>
The attributes <i>soap.proxy_host</i> and <i>soap.proxy_port</i> keep their values through a sequence of service operation calls,
so they only need to be set once.

<div class="p"><!----></div>
When X-Forwarded-For headers are returned by the proxy, the header can be accessed in the <i>soap.proxy_from</i> string.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.31">
19.31</a>&nbsp;&nbsp;<font color="#0000FF">FastCGI Support</font></h3><a name="sec:fastcgi">
</a>

<div class="p"><!----></div>
To enable FastCGI support, install FastCGI and compile <em>all</em> sources (do
not use <i>libgsoap</i> but compile <i>stdsoap2.c</i>) and your application
sources with option <i>-DWITH_FASTCGI</i> or add
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#define WITH_FASTCGI
</td></tr></table><br></i>
to <i>stdsoap2.h</i> and recompile the project code.

<div class="p"><!----></div>
<font color="#FF0000"><b>Caution</b></font>: Do not link against the <i>libgsoap</i> libraries as these are not
suitable for FastCGI. Compile <i>stdsoap2.c</i> (or <i>stdsoap2.cpp</i>) instead.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.32">
19.32</a>&nbsp;&nbsp;<font color="#0000FF">How to Create gSOAP Applications With a Small Memory Footprint</font></h3><a name="sec:lean">
</a>

<div class="p"><!----></div>
To compile gSOAP applications intended for small memory devices, you may want
to remove all non-essential features that consume precious code and data space.
To do this, compile the gSOAP sources with <i>-DWITH_LEAN</i> (i.e.&nbsp;<i>#define WITH_LEAN</i>) to remove many
non-essential features. The features that will be disabled are:

<ul>
<li> No I/O timeouts. Note that many socket operations already obey some form of timeout handling, such as a connect timeout for example.
<div class="p"><!----></div>
</li>

<li> No UDP support
<div class="p"><!----></div>
</li>

<li> No HTTP keep alive
<div class="p"><!----></div>
</li>

<li> No HTTP cookies
<div class="p"><!----></div>
</li>

<li> No HTTP authentication
<div class="p"><!----></div>
</li>

<li> No HTTP chunked output (but input is OK)
<div class="p"><!----></div>
</li>

<li> No HTTP compressed output (but input is OK when compiled with <i>WITH_GZIP</i>)
<div class="p"><!----></div>
</li>

<li> No send/recv timeouts
<div class="p"><!----></div>
</li>

<li> No socket flags (no <i>soap.socket_flag, soap.connect_flag, soap.bind_flag, soap.accept_flag</i>)
<div class="p"><!----></div>
</li>

<li> No canonical XML output
<div class="p"><!----></div>
</li>

<li> No logging
<div class="p"><!----></div>
</li>

<li> Limited TCP/IP and HTTP error diagnostic messages
<div class="p"><!----></div>
</li>

<li> No support for <i>time_t</i> serialization
<div class="p"><!----></div>
</li>

<li> No support for <i>hexBinary</i> XML attribute serialization (remap <i>hexBinary</i> to strings by adding a remap entry to typemap.dat)
<div class="p"><!----></div>
</li>
</ul>
Use <i>-DWITH_LEANER</i> to make the executable even smaller by removing DIME
and MIME attachment handling, <i>LONG64</i> (64 bit) serialization, <i>wchar_t*</i> serialization, and support for XML DOM operations.
Note that DIME/MIME attachments are not essential to achieve
SOAP/XML interoperability.  DIME attachments are a convenient way to exchange
non-text-based (i.e.&nbsp;binary) content, but are not required for basic SOAP/XML
interoperability.  Attachment requirements are predictable.  That is,
applications won't suddenly decide to use DIME or MIME instead of XML to exchange
content.

<div class="p"><!----></div>
It is safe to try to compile your application with <i>-DWITH_LEAN</i>, provided
that your application does not rely on I/O timeouts. When no linkage error
occurs in the compilation process, it is safe to assume that your application
will run just fine.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.33">
19.33</a>&nbsp;&nbsp;<font color="#0000FF">How to Eliminate BSD Socket Library Linkage</font></h3><a name="sec:noio">
</a>

<div class="p"><!----></div>
The <i>stdsoap2.c</i> and <i>stdsoap2.cpp</i> gSOAP runtime libraries should be linked with a BSD socket library in the project build, e.g. winsock2 for Win32. To eliminate the need to link a socket library, you can compile <i>stdsoap2.c</i> (for C) and <i>stdsoap2.cpp</i> (for C++) with the <i>-DWITH_NOIO</i> macro set (i.e.&nbsp;<i>#define WITH_NOIO</i>). This eliminates the dependency on the BSD socket API, IO streams, <i>FILE</i> type, and <i>errno</i>.

<div class="p"><!----></div>
As a consequence, you MUST define callbacks to replace the missing socket stack. To do so, add to your code the following definitions:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
/* fsend is used to transmit data in blocks */ <br />
soap.fsend = my_send; <br />
/* frecv is used to receive data in blocks */ <br />
soap.frecv = my_recv; <br />
/* fopen is used to connect */ <br />
soap.fopen = my_tcp_connect; <br />
/* fclose is used to disconnect */ <br />
soap.fclose = my_tcp_disconnect; <br />
/* fclosesocket is used only to close the master socket in a server upon soap_done() */ <br />
soap.fclosesocket = my_tcp_closesocket; <br />
/* fshutdownsocket is used after completing a send operation to send TCP FIN */ <br />
soap.fshutdownsocket = my_tcp_shutdownsocket; <br />
/* setting fpoll is optional, leave it NULL to omit polling the server */ <br />
soap.fpoll = my_poll; <br />
/* faccept is used only by a server application */ <br />
soap.faccept = my_accept;
</td></tr></table><br></i>
These functions are supposed to provide a (minimal) transport stack.
See Section&nbsp;<a href="#sec:callback">19.7</a> for more details on the use of these callbacks.
All callback function pointers should be non-NULL, except <i>fpoll</i>.

<div class="p"><!----></div>
You cannot use <i>soap_print_fault</i> and <i>soap_print_fault_location</i> to print error diagnostics. Instead, the value of <i>soap.error</i>, which contains the gSOAP error code, can be used to determine the cause of a fault.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.34">
19.34</a>&nbsp;&nbsp;<font color="#0000FF">How to Combine Multiple Client and Server Implementations into one Executable</font></h3>

<div class="p"><!----></div>
The <i>wsdl2h</i> tool can be used to import multiple WSDLs and schemas at once.
The service definitions are combined in one header file to be parsed by
<i>soapcpp2</i>. It is important to assign namespace prefixes to namespace URIs
using the <i>typemap.dat</i> file. Otherwise, <i>wsdl2h</i> will assign namespace
prefixes <i>ns1</i>, <i>ns2</i>, and so on to the service operations and schema
types. Thus, any change to a WSDL or schema may result in a new prefix
assignment. For more details, please see Section&nbsp;<a href="#sec:typemap">8.2</a>.

<div class="p"><!----></div>
Another approach to combine multiple client and service applications into one
executable is by using C++ namespaces to structurally separate the definitions
or by creating C libraries for the client/server objects as explained in
subsequent sections. This is automated with <i>wsdl2h</i> option <i>-q</i>.

<div class="p"><!----></div>
Both approaches are demonstrated by example in the gSOAP distribution, the <i>samples/link</i> (C only) and <i>samples/link++</i> (C++ with C++ namespaces) examples.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.35">
19.35</a>&nbsp;&nbsp;<font color="#0000FF">How to Build a Client or Server in a C++ Code Namespace</font></h3><a name="sec:codenamespace">
</a>

<div class="p"><!----></div>
You can use a C++ code namespace of your choice in your header file to build
a client or server in that code namespace. In this way, you can create multiple
clients and servers that can be combined and linked together without conflicts,
which is explained in more detail in the next section (which also shows an
example combining two client libraries defined in two C++ code namespaces).

<div class="p"><!----></div>
Use <i>wsdl2h</i> option <i>-q</i><i>name</i> to generate definitions in the C++ <i>name</i> namespace. This option can also be used in combination with C++ proxy and server object generation, using <i>soapcpp2</i> options <i>-i</i> (or <i>-j</i>) and <i>-p</i>.

<div class="p"><!----></div>
At most one namespace can be defined for the entire gSOAP header file. The code
namespace MUST completely encapsulate the entire contents of the header file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>namespace</b>&nbsp;myNamespaceName { <br />
... gSOAP header file contents ... <br />
}
</td></tr></table><br></i>
When compiling this header file with the gSOAP <i>soapcpp2</i> compiler, all type definitions,
the (de)serializers for these types, and the stub/skeleton codes will be placed
in this namespace. The XML namespace mapping table (saved in a <i>.nsmap</i>
file) will not be placed in the code namespace to allow it to be linked as a
global object. You can use option <i>-n</i> to create local XML namespace
tables, see Section&nbsp;<a href="#sec:options">9.1</a> (but remember that you explicitly need to
initialize the <i>soap.namespaces</i> to point to a table at run time). The
generated files are prefixed with the code namespace name instead of the usual
<i>soap</i> file name prefix to enable multiple client/server codes to be build
in the same project directory (a code namespace automatically sets the <i>-p</i>
compiler option, see Section&nbsp;<a href="#sec:options">9.1</a> for options).

<div class="p"><!----></div>
Because the SOAP Header and Fault serialization codes will also be placed in
the namespace, they cannot be called from the <i>stdsoap2.cpp</i> run time
library code and are therefore rendered unusable. Therefore, these serializers
are not compiled at all (enforced with <i>#define WITH_NOGLOBAL</i>). To add SOAP
Header and Fault serializers, you MUST compile them separately as follows.
First, create a new header file <i>env.h</i> with the SOAP Header and Fault
definitions.  You can leave this header file empty if you want to use the
default SOAP Header and Fault. Then compile this header file with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -penv env.h</i>
</td></tr></table><br></span>
The generated <i>envC.cpp</i> file holds the SOAP Header and Fault serializers and you can
link this file with your client or server application.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.36">
19.36</a>&nbsp;&nbsp;<font color="#0000FF">How to Create Client/Server Libraries</font></h3><a name="sec:dylibs">
</a>

<div class="p"><!----></div>
The gSOAP <i>soapcpp2</i> compiler produces <i>soapClientLib.cpp</i> and <i>soapServerLib.cpp</i>
codes that are specifically intended for building static or dynamic
client/server libraries. These codes export the stubs and skeletons, but keep
all marshaling code (i.e.&nbsp;parameter serializers and deserializers) local (i.e.&nbsp;
as static functions) to avoid link symbol conflicts when combining multiple
clients and/or servers into one executable. Note that it is far simpler to use
the <i>wsdl2h</i> tool on multiple WSDL files to generate a header file that
combines all service definitions. However, the approach presented in this
section is useful when creating (dynamic) libraries for client and server
objects, such as DLLs as described in Section&nbsp;<a href="#sec:dll">19.37</a>.

<div class="p"><!----></div>
Do not link <i>soapClientLib.cpp</i> or <i>soapServerLib.cpp</i> together with <i>soapC.cpp</i>, <i>soapClient.cpp</i>, and <i>soapServer.cpp</i>. The library versions already include all of the necessary definitions.

<div class="p"><!----></div>
To build multiple libraries in the same project directory, you can define a C++
code namespace in your header file (see Section&nbsp;<a href="#sec:codenamespace">19.35</a>) or you
can use <i>soapcpp2</i> with option <i>-p</i> to rename the generated
<i>soapClientLib.cpp</i> and <i>soapServerLib.cpp</i> (and associated) files. The
<i>-p</i> option specifies the file name prefix to replace the <i>soap</i>
prefix.  The libraries don't have to be C++ codes. You can use option <i>-c</i>
to generate C code. A clean separation of libraries can also be achieved with
C++ code namespaces, see Section&nbsp;<a href="#sec:codenamespace">19.35</a>.

<div class="p"><!----></div>
The library codes do not define SOAP Header and Fault serializers.  You MUST
add SOAP Header and Fault serializers to your application, which are compiled
separately as follows.  First, create a new header file <i>env.h</i> with the
SOAP Header and Fault definitions.  You can leave this header file empty if you
want to use the default SOAP Header and Fault. Then compile this header file
with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -penv env.h</i>
</td></tr></table><br></span>
The generated <i>envC.cpp</i> file holds the SOAP Header and Fault serializers and you can
create a (dynamic) library for it to link this code with your client or server application.

<div class="p"><!----></div>
You MUST compile the <i>stdsoap2.cpp</i> library using <i>-DWITH_NONAMESPACES</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -DWITH_NONAMESPACES -c stdsoap2.cpp</i>
</td></tr></table><br></span>
This omits the reference to the global namespaces table, which is nowhere
to be defined since we will use XML namespaces for each client/service separately. Therefore, you MUST explicitly set the
namespaces value of the gSOAP context in your code every time after initialization of the soap struct with the <i>soap_set_namespaces(<b>struct</b>&nbsp;soap*, <b>const</b>&nbsp;<b>struct</b>&nbsp;Namespace*)</i> function.

<div class="p"><!----></div>
For example, suppose we have two clients defined in header files <i>client1.h</i> and <i>client2.h</i>. We first generate the <i>envH.h</i> file for the SOAP Header and Fault definitions:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -c -penv env.h</i>
</td></tr></table><br></span>
Then we generate the code for client1 and client2:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -c -n -pmyClient1 client1.h</i> <br />
<i> &gt;  soapcpp2 -c -n -pmyClient2 client2.h</i>
</td></tr></table><br></span>
This generates <i>myClient1ClientLib.c</i> and <i>myClient2ClientLib.c</i> (among many other files).
These two files should be compiled and linked with your application.
The source code of your application should include the generated <i>envH.h</i>, <i>myClient1H.h</i>, <i>myClient2.h</i> files and <i>myClient1.nsmap</i>, <i>myClient2.nsmap</i> files:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "envH.h" // include this file first! <br />
#include "myClient1H.h" // include client 1 stubs <br />
#include "myClient2H.h" // include client 2 stubs <br />
... <br />
#include "myClient1H.nsmap" // include client 1 nsmap <br />
#include "myClient2H.nsmap" // include client 2 nsmap <br />
... <br />
soap_init(&amp;soap); <br />
soap_set_namespaces(&amp;soap, myClient1_namespaces); <br />
... make Client 1 invocations ... <br />
... <br />
soap_set_namespaces(&amp;soap, myClient2_namespaces); <br />
... make Client 2 invocations ...
</td></tr></table><br></i>
It is important to use <i>soapcpp2</i> option <i>-n</i>, see Section&nbsp;<a href="#sec:options">9.1</a>, to rename the namespace tables so we can include them all without running into redefinitions.

<div class="p"><!----></div>
Note: Link conflicts may still occur in the unlikely situation that identical service operation names are defined in
two or more client stubs or server skeletons when these methods share the same XML namespace prefix.  You may have to use C++ code
namespaces to avoid these link conflicts or rename the namespace prefixes used by the service operation defined in the header files.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.36.1">
19.36.1</a>&nbsp;&nbsp;<font color="#0000FF">C++ Clients Example</font></h4>

<div class="p"><!----></div>
As an example we will build a Delayed Stock Quote client library and a Currency Exchange Rate client library.

<div class="p"><!----></div>
First, we create an empty header file <i>env.h</i> (which may contain optional SOAP Header and Fault definitions), and compile it as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -penv env.h</i> <br />
<i> &gt;  c++ -c envC.cpp</i> <br />
</td></tr></table><br></span>
We also compile <i>stdsoap2.cpp</i> without namespaces:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  c++ -c -DWITH_NONAMESPACES stdsoap2.cpp</i>
</td></tr></table><br></span>
Note: when you forget to use <i>-DWITH_NONAMESPACES</i> you will get an unresolved link error for the global <i>namespaces</i> table. You can define a dummy table to avoid having to recompile <i>stdsoap2.cpp</i>.

<div class="p"><!----></div>
Second, we create the Delayed Stock Quote header file specification, which may be obtained using the WSDL importer. If you want to use C++ namespaces then you need to manually add the <i><b>namespace</b></i> declaration to the generated header file:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>namespace</b>&nbsp;quote { <br />
//gsoap ns service name: Service <br />
//gsoap ns service style: rpc <br />
//gsoap ns service encoding: encoded <br />
//gsoap ns service location: http://services.xmethods.net/soap <br />
//gsoap ns schema namespace: urn:xmethods-delayed-quotes <br />
//gsoap ns service method-action: getQuote "" <br />
<b>int</b>&nbsp;ns__getQuote(<b>char</b>&nbsp;*symbol, <b>float</b>&nbsp;&amp;Result); <br />
}
</td></tr></table><br></i>
We then compile it as a library and we use option <i>-n</i> to rename the namespace table to avoid link conflicts later:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -n quote.h</i> <br />
<i> &gt;  c++ -c quoteClientLib.cpp</i>
</td></tr></table><br></span>
If you don't want to use a C++ code namespace, you should compile <i>quote.h</i> "as is" with soapcpp2 option <i>-pquote</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -n -pquote quote.h</i> <br />
<i> &gt;  c++ -c quoteClientLib.cpp</i>
</td></tr></table><br></span>
Third, we create the Currency Exchange Rate header file specification:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>namespace</b>&nbsp;rate { <br />
//gsoap ns service name: Service <br />
//gsoap ns service style: rpc <br />
//gsoap ns service encoding: encoded <br />
//gsoap ns service location: http://services.xmethods.net/soap <br />
//gsoap ns schema namespace: urn:xmethods-CurrencyExchange <br />
//gsoap ns service method-action: getRate "" <br />
<b>int</b>&nbsp;ns__getRate(<b>char</b>&nbsp;*country1, <b>char</b>&nbsp;*country2, <b>float</b>&nbsp;&amp;Result); <br />
}
</td></tr></table><br></i>
Similar to the Quote example above, we compile it as a library and we use option <i>-n</i> to rename the namespace table to avoid link conflicts:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -n rate.h</i> <br />
</td></tr></table><br></span>
Fourth, we consider linking the libraries to the main program.
The main program can import the <i>quoteServiceProxy.h</i> and <i>rateServiceProxy.h</i> files to obtain client proxies to invoke the services. The proxy implementations are defined in <i>quoteClient.cpp</i>.
The <i>-n</i> option also affects the generation of the C++ proxy codes to ensure that the gSOAP context is properly initialized with the appropriate namespace table (so you don't have to initialize explicitly - this feature is only available with C++ proxy and server object classes).
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "quoteServiceProxy.h" // get quote Service proxy <br />
#include "rateServiceProxy.h" // get rate Service proxy <br />
#include "quote.nsmap" // get quote namespace bindings <br />
#include "rate.nsmap" // get rate namespace bindings <br />
<b>int</b>&nbsp;main(<b>int</b>&nbsp;argc, <b>char</b>&nbsp;*argv[]) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(argc  &lt; = 1) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;std::cerr <tt>&lt;&lt;</tt> "Usage: main ticker [currency]" <tt>&lt;&lt;</tt> std::endl <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(0); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;quote::Service quote; <br />
&nbsp;&nbsp;&nbsp;<b>float</b>&nbsp;q; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(quote.getQuote(argv[1], q)) // get quote <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(quote.soap, stderr); <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(argc  &gt;  2) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rate::Service rate; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>float</b>&nbsp;r; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(rate.getRate("us", argv[2], r)) // get rate in US dollars <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(rate.soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;q *= r; // convert the quote <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;std::cout <tt>&lt;&lt;</tt> argv[1] <tt>&lt;&lt;</tt> ": " <tt>&lt;&lt;</tt> q <tt>&lt;&lt;</tt> std::endl; <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
}
</td></tr></table><br></i>
Compile and link this application with <i>stdsoap2.o</i>, <i>envC.o</i>, <i>quoteServerProxy.o</i>, and <i>rateServerProxy.o</i>.

<div class="p"><!----></div>
To compile and link a server object is very similar. For example, assume that we need to implement a calculator service and we want to create a library for it.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>namespace</b>&nbsp;calc { <br />
//gsoap ns service name: Service <br />
//gsoap ns service style: rpc <br />
//gsoap ns service encoding: encoded <br />
//gsoap ns service location: http://www.cs.fsu.edu/~engelen/calc.cgi <br />
//gsoap ns schema namespace: urn:calc <br />
<b>int</b>&nbsp;ns__add(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
<b>int</b>&nbsp;ns__sub(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
<b>int</b>&nbsp;ns__mul(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
<b>int</b>&nbsp;ns__div(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
}
</td></tr></table><br></i>
We compile this with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -n calc.h</i> <br />
</td></tr></table><br></span>
The effect of the <i>-n</i> option is that it creates local namespace tables, and a modified <i>calcServiceObject.h</i> server class definitions that properly initialize the gSOAP run time with the table.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "calcServiceObject.h" // get Service object <br />
#include "calc.nsmap" // get calc namespace bindings <br />
... <br />
calc::Service calc; <br />
calc.serve(); // calls request dispatcher to invoke one of the functions below <br />
... <br />
<b>int</b>&nbsp;calc::Service::add(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
{ result = a + b; <b>return</b>SOAP_OK; } <br />
<b>int</b>&nbsp;calc::Service::sub(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
{ result = a - b; <b>return</b>SOAP_OK; } <br />
<b>int</b>&nbsp;calc::Service::mul(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
{ result = a * b; <b>return</b>SOAP_OK; } <br />
<b>int</b>&nbsp;calc::Service::div(<b>double</b>&nbsp;a, <b>double</b>&nbsp;b, <b>double</b>&nbsp;&amp;result); <br />
{ result = a / b; <b>return</b>SOAP_OK; } <br />
</td></tr></table><br></i>
In fact, the <i>calc::Service</i> class is derived from the <i><b>struct</b>&nbsp;soap</i>. So the context
is available as <i>this</i>, which can be passed to all gSOAP functions that require a soap struct
context.

<div class="p"><!----></div>
The example above serves requests over stdin/out. Use the bind and accept calls to create a stand-alone server to service inbound requests over sockets, see&nbsp;<a href="#sec:stand-alone">7.2.3</a>.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.36.2">
19.36.2</a>&nbsp;&nbsp;<font color="#0000FF">C Clients Example</font></h4>

<div class="p"><!----></div>
This is the same example as above, but the clients are build with pure C.

<div class="p"><!----></div>
We create a <i>env.h</i> that contains the joint SOAP Header and SOAP Fault
definitions. You may have to copy-paste these from the other header files.
Then, compile it as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -c -penv env.h</i> <br />
<i> &gt;  cc -c envC.c</i> <br />
</td></tr></table><br></span>
We also compile <i>stdsoap2.c</i> without namespaces:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  cc -c -DWITH_NONAMESPACES stdsoap2.c</i>
</td></tr></table><br></span>
Second, we create the Delayed Stock Quote header file specification, which may be obtained using the WSDL importer.
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service name: Service <br />
//gsoap ns service style: rpc <br />
//gsoap ns service encoding: encoded <br />
//gsoap ns service location: http://services.xmethods.net/soap <br />
//gsoap ns schema namespace: urn:xmethods-delayed-quotes <br />
//gsoap ns service method-action: getQuote "" <br />
<b>int</b>&nbsp;ns__getQuote(<b>char</b>&nbsp;*symbol, <b>float</b>&nbsp;*Result);
</td></tr></table><br></i>
We compile it as a library and we use options <i>-n</i> and <i>-p</i> to rename the namespace table to avoid link conflicts:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -c -n -pquote quote.h</i> <br />
<i> &gt;  cc -c quoteClientLib.c</i>
</td></tr></table><br></span>
Third, we create the Currency Exchange Rate header file specification:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
//gsoap ns service name: Service <br />
//gsoap ns service style: rpc <br />
//gsoap ns service encoding: encoded <br />
//gsoap ns service location: http://services.xmethods.net/soap <br />
//gsoap ns schema namespace: urn:xmethods-CurrencyExchange <br />
//gsoap ns service method-action: getRate "" <br />
<b>int</b>&nbsp;ns__getRate(<b>char</b>&nbsp;*country1, <b>char</b>&nbsp;*country2, <b>float</b>&nbsp;*Result);
</td></tr></table><br></i>
We compile it as a library and we use options <i>-n</i> and <i>-p</i> to rename the namespace table to avoid link conflicts:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -c -n -prate rate.h</i> <br />
<i> &gt;  cc -c rateClientLib.c</i>
</td></tr></table><br></span>
The main program is:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "quoteStub.h" // get quote Service stub <br />
#include "rateStub.h" // get rate Service stub <br />
#include "quote.nsmap" // get quote namespace bindings <br />
#include "rate.nsmap" // get rate namespace bindings <br />
<b>int</b>&nbsp;main(<b>int</b>&nbsp;argc, <b>char</b>&nbsp;*argv[]) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(argc  &lt; = 1) <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr, "Usage: main ticker [currency]\n"); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(0); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;soap soap; <br />
&nbsp;&nbsp;&nbsp;<b>float</b>&nbsp;q; <br />
&nbsp;&nbsp;&nbsp;soap_init(&amp;soap); <br />
&nbsp;&nbsp;&nbsp;soap_set_namespaces(&amp;soap, quote_namespaces); <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_ns__getQuote(&amp;soap, "http://services.xmethods.net/soap", "", argv[1], &amp;q)) // get quote <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(argc  &gt;  2) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_set_namespaces(&amp;soap, rate_namespaces); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>float</b>&nbsp;r; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_ns__getRate(&amp;soap, "http://services.xmethods.net/soap", "", "us", argv[2], &amp;r)) // get rate in US dollars <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>else</b><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;q *= r; // convert the quote <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf("%s: %f \n", argv[1], q); <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;0; <br />
}
</td></tr></table><br></i>
Compile and link this application with <i>stdsoap2.o</i>, <i>envC.o</i>, <i>quoteClientLib.o</i>, and <i>rateClientLib.o</i>.

<div class="p"><!----></div>
To compile and link a server library is very similar. Assuming that the server is named "<i>calc</i>" (as specified with options <i>-n</i> and <i>-p</i>), the application needs to include the <i>calcStub.h</i> file, link the <i>calcServerLib.o</i> file, and call <i>calc_serve(&amp;soap)</i> function at run time.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.36.3">
19.36.3</a>&nbsp;&nbsp;<font color="#0000FF">C Services Chaining Example</font></h4>

<div class="p"><!----></div>
We build a C application for multiple services served on one port.

<div class="p"><!----></div>
We create a <i>env.h</i> that contains the joint SOAP Header and SOAP Fault
definitions. You may have to copy-paste these from the other header files.
Then, compile it as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -c -penv env.h</i> <br />
<i> &gt;  cc -c envC.c</i> <br />
</td></tr></table><br></span>
We also compile <i>stdsoap2.c</i> without namespaces:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  cc -c -DWITH_NONAMESPACES stdsoap2.c</i>
</td></tr></table><br></span>
Say we have a service definition in <i>quote.h</i>. We compile it as a library and we use options <i>-n</i> and <i>-p</i> to rename the namespace table to avoid link conflicts:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -c -n -pquote quote.h</i> <br />
<i> &gt;  cc -c quoteClientLib.c</i>
</td></tr></table><br></span>
We do the same for a service definition in <i>rate.h</i>:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -c -n -prate rate.h</i> <br />
<i> &gt;  cc -c rateClientLib.c</i>
</td></tr></table><br></span>
To serve both the quote and rate services on the same port, we chain the service dispatchers as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap *soap = soap_new(); <br />
soap_bind(soap, NULL, 8080, 100); <br />
soap_accept(soap); <br />
<b>if</b>&nbsp;(soap_begin_serve(soap)) <br />
&nbsp;&nbsp;&nbsp;soap_send_fault(&amp;abc); // send fault to client <br />
<b>else</b>&nbsp;<b>if</b>&nbsp;(quote_serve_request(soap) == SOAP_NO_METHOD) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(rate_serve_request(soap))
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_send_fault(soap); // send fault to client <br />
} <br />
<b>else</b>&nbsp;<b>if</b>&nbsp;(soap.error) <br />
&nbsp;&nbsp;&nbsp;soap_send_fault(soap); // send fault to client <br />
soap_destroy(soap); <br />
soap_end(soap); <br />
soap_free(soap);
</td></tr></table><br></i>
This chaining can be arbitrarily deep. When the previous request fails with a <i>SOAP_NO_METHOD</i> then next request dispatcher can be tried.

<div class="p"><!----></div>
The server should also define the service operations:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;ns__getQuote(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*symbol, <b>float</b>&nbsp;*Result); <br />
{ *Result = ... ; <br />
  &nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
<b>int</b>&nbsp;ns__getRate(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*country1, <b>char</b>&nbsp;*country2, <b>float</b>&nbsp;*Result); <br />
{ *Result = ... ; <br />
  &nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.37">
19.37</a>&nbsp;&nbsp;<font color="#0000FF">How to Create DLLs</font></h3><a name="sec:dll">
</a>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.37.1">
19.37.1</a>&nbsp;&nbsp;<font color="#0000FF">Create the Base stdsoap2.dll</font></h4>

<div class="p"><!----></div>
First, create a new header file <i>env.h</i> with the SOAP Header and Fault
definitions.  You can leave this header file empty if you want to use the
default SOAP Header and Fault. Then compile this header file with:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i> &gt;  soapcpp2 -penv env.h</i>
</td></tr></table><br></span>
The generated <i>envC.cpp</i> file holds the SOAP Header and Fault serializers, which need to be part of the base library functions.

<div class="p"><!----></div>
The next step is to create <i>stdsoap2.dll</i> which consists of the file
<i>stdsoap2.cpp</i> and <i>envC.cpp</i>. This DLL contains all common functions
needed for all other clients and servers based on gSOAP.  Compile
<i>envC.cpp</i> and <i>stdsoap2.cpp</i> into <i>stdsoap2.dll</i> using the C++
compiler option <i>-DWITH_NONAMESPACES</i> and the MSVC Pre-Processor
definitions <i>SOAP_FMAC1=__declspec(dllexport)</i> and <i>SOAP_FMAC3=__declspec(dllexport)</i> (or you
can compile with
<i>-DWITH_SOAPDEFS_H</i> and put the macro definitions in <i>soapdefs.h</i>).
This exports all functions which are preceded by the macro <i>SOAP_FMAC1</i> in
the <i>soapcpp2.cpp</i> source file and macro <i>SOAP_FMAC3</i> in the <i>envC.cpp</i> source file.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.37.2">
19.37.2</a>&nbsp;&nbsp;<font color="#0000FF">Creating Client and Server DLLs</font></h4>

<div class="p"><!----></div>
Compile the <i>soapClientLib.cpp</i> and <i>soapServerLib.cpp</i> sources as DLLs
by using the MSVC Pre-Processor definitions <i>SOAP_FMAC5=__declspec(dllexport)</i> and <i>SOAP_CMAC=__declspec(dllexport)</i>, and by using the C++ compiler option <i>-DWITH_NONAMESPACES</i>.
This DLL links to <i>stdsoap2.dll</i>.

<div class="p"><!----></div>
To create multiple DLLs in the same project directory, you SHOULD use option
<i>-p</i> to rename the generated <i>soapClientLib.cpp</i> and
<i>soapServerLib.cpp</i> (and associated) files. The <i>-p</i> option specifies
the file name prefix to replace the <i>soap</i> prefix.
A clean separation of libraries can also be achieved with C++ namespaces, see Section&nbsp;<a href="#sec:codenamespace">19.35</a>.

<div class="p"><!----></div>
Unless you use the client proxy and server object classes (<i>soapXProxy.h</i> and <i>soapXObject.h</i> where <i>X</i> is the name of the service), all client and server applications MUST explicitly set the namespaces value of the gSOAP context:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_init(&amp;soap); <br />
soap_set_namespaces(&amp;soap, namespaces);
</td></tr></table><br></i>
where the <i>namespaces[]</i> table should be defined in the client/server source. These tables are generated in the <i>.nsmap</i> files. You can rename the tables using option <i>-n</i>, see Section&nbsp;<a href="#sec:options">9.1</a>.

<div class="p"><!----></div>
	     <h3><a name="tth_sEc19.38">
19.38</a>&nbsp;&nbsp;<font color="#0000FF">gSOAP Plug-ins</font></h3><a name="sec:plugins">
</a>

<div class="p"><!----></div>
The gSOAP plug-in feature enables a convenient extension mechanism of gSOAP
capabilities. When the plug-in registers with gSOAP, it has full access
to the run-time settings and the gSOAP function callbacks.
Upon registry, the plug-in's local data is associated with the gSOAP run-time.
By overriding gSOAP's function callbacks with the plug-in's function callbacks,
the plug-in can extend gSOAP's capabilities. The local plug-in data can be
accessed through a lookup function, usually invoked within a callback function
to access the plug-in data. 
The registry and lookup functions are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i><b>int</b>&nbsp;soap_register_plugin_arg(<b>struct</b>&nbsp;soap *soap, <b>int</b>&nbsp;(*fcreate)(<b>struct</b>&nbsp;soap *soap, <b>struct</b>&nbsp;soap_plugin *p, <b>void</b>&nbsp;*arg), <b>void</b>&nbsp;*arg)</i> <br />
<i><b>void</b>* soap_lookup_plugin(<b>struct</b>&nbsp;soap*, <b>const</b>&nbsp;<b>char</b>*);</i>
</td></tr></table><br></span>
Other functions that deal with plug-ins are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">
<i><b>int</b>&nbsp;soap_copy(<b>struct</b>&nbsp;soap *soap);</i> <br />
<i><b>void</b>&nbsp;soap_done(<b>struct</b>&nbsp;soap *soap);</i>
</td></tr></table><br></span>
The <i>soap_copy</i> function returns a new dynamically allocated gSOAP
context that is a copy of another, such that no data is shared between the
copy and the original context. The <i>soap_copy</i> function invokes the
plug-in copy callbacks to copy the plug-ins' local data.
The <i>soap_copy</i> function returns a gSOAP error code or <i>SOAP_OK</i>.
The <i>soap_done</i> function de-registers all plugin-ins, so this function
should be called to cleanly terminate a gSOAP run-time context.

<div class="p"><!----></div>
An example will be used to illustrate these functions.
This example overrides the send and receive callbacks to copy all messages
that are sent and received to the terminal (stderr).

<div class="p"><!----></div>
First, we write a header file <i>plugin.h</i> to define the local plug-in data
structure(s) and we define a global name to identify the plug-in:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "stdsoap2.h" <br />
#define PLUGIN_ID "PLUGIN-1.0" // some name to identify plugin <br />
<b>struct</b>&nbsp;plugin_data // local plugin data <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>int</b>&nbsp;(*fsend)(<b>struct</b>&nbsp;soap*, <b>const</b>&nbsp;<b>char</b>*, size_t); // to save and use send callback <br />
&nbsp;&nbsp;&nbsp;size_t (*frecv)(<b>struct</b>&nbsp;soap*, <b>char</b>*, size_t); // to save and use recv callback <br />
}; <br />
<b>int</b>&nbsp;plugin(<b>struct</b>&nbsp;soap *soap, <b>struct</b>&nbsp;soap_plugin *plugin, <b>void</b>&nbsp;*arg);
</td></tr></table><br></i>
Then, we write the plugin registry function and the callbacks:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "plugin.h" <br />
<b>static</b>&nbsp;<b>const</b>&nbsp;<b>char</b>&nbsp;plugin_id[] = PLUGIN_ID; // the plugin id <br />
<b>static</b>&nbsp;<b>int</b>&nbsp;plugin_init(<b>struct</b>&nbsp;soap *soap, <b>struct</b>&nbsp;plugin_data *data); <br />
<b>static</b>&nbsp;<b>int</b>&nbsp;plugin_copy(<b>struct</b>&nbsp;soap *soap, <b>struct</b>&nbsp;soap_plugin *dst, <b>struct</b>&nbsp;soap_plugin *src); <br />
<b>static</b>&nbsp;<b>void</b>&nbsp;plugin_delete(<b>struct</b>&nbsp;soap *soap, <b>struct</b>&nbsp;soap_plugin *p); <br />
<b>static</b>&nbsp;<b>int</b>&nbsp;plugin_send(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*buf, size_t len); <br />
<b>static</b>&nbsp;size_t plugin_recv(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*buf, size_t len); <br />
// the registry function: <br />
<b>int</b>&nbsp;plugin(<b>struct</b>&nbsp;soap *soap, <b>struct</b>&nbsp;soap_plugin *p, <b>void</b>&nbsp;*arg) <br />
{ <br />
&nbsp;&nbsp;&nbsp;p<tt>-&gt;</tt>id = plugin_id; <br />
&nbsp;&nbsp;&nbsp;p<tt>-&gt;</tt>data = (<b>void</b>*)malloc(<b>sizeof</b>(<b>struct</b>&nbsp;plugin_data)); <br />
&nbsp;&nbsp;&nbsp;p<tt>-&gt;</tt>fcopy = plugin_copy; /* optional: when set the plugin must copy its local data */<br />
&nbsp;&nbsp;&nbsp;p<tt>-&gt;</tt>fdelete = plugin_delete; <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(p<tt>-&gt;</tt>data) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(plugin_init(soap, (<b>struct</b>&nbsp;plugin_data*)p<tt>-&gt;</tt>data)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;free(p<tt>-&gt;</tt>data); // error: could not init <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_EOM; // return error <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
<b>static</b>&nbsp;<b>int</b>&nbsp;plugin_init(<b>struct</b>&nbsp;soap *soap, <b>struct</b>&nbsp;plugin_data *data) <br />
{ <br />
&nbsp;&nbsp;&nbsp;data<tt>-&gt;</tt>fsend = soap<tt>-&gt;</tt>fsend; // save old recv callback <br />
&nbsp;&nbsp;&nbsp;data<tt>-&gt;</tt>frecv = soap<tt>-&gt;</tt>frecv; // save old send callback <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>fsend = plugin_send; // replace send callback with new <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>frecv = plugin_recv; // replace recv callback with new <br />
&nbsp;&nbsp;&nbsp;return SOAP_OK; <br />
} <br />
// copy plugin data, called by soap_copy()
// This is important: we need a deep copy to avoid data sharing by two run-time contexts <br />
<b>static</b>&nbsp;<b>int</b>&nbsp;plugin_copy(<b>struct</b>&nbsp;soap *soap, struct soap_plugin *dst, <b>struct</b>&nbsp;soap_plugin *src) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!(dst<tt>-&gt;</tt>data = (<b>struct</b>&nbsp;plugin_data*)malloc(<b>sizeof</b>(<b>struct</b>&nbsp;plugin_data)))) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_EOM; <br />
&nbsp;&nbsp;&nbsp;*dst<tt>-&gt;</tt>data = *src<tt>-&gt;</tt>data; <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
} <br />
// plugin deletion, called by soap_done() <br />
<b>static</b>&nbsp;<b>void</b>&nbsp;plugin_delete(<b>struct</b>&nbsp;soap *soap, <b>struct</b>&nbsp;soap_plugin *p) <br />
{ free(p<tt>-&gt;</tt>data); // free allocated plugin data <br />
} <br />
// the new send callback <br />
<b>static</b>&nbsp;<b>int</b>&nbsp;plugin_send(<b>struct</b>&nbsp;soap *soap, <b>const</b>&nbsp;<b>char</b>&nbsp;*buf, size_t len) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;plugin_data *data = (<b>struct</b>&nbsp;plugin_data*)soap_lookup_plugin(soap, plugin_id); // fetch plugin's local data <br />
&nbsp;&nbsp;&nbsp;fwrite(buf, len, 1, stderr); // write message to stderr <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;data<tt>-&gt;</tt>fsend(soap, buf, len); // pass data on to old send callback <br />
} <br />
// the new receive callback <br />
<b>static</b>&nbsp;size_t plugin_recv(<b>struct</b>&nbsp;soap *soap, <b>char</b>&nbsp;*buf, size_t len) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;plugin_data *data = (<b>struct</b>&nbsp;plugin_data*)soap_lookup_plugin(soap, plugin_id); // fetch plugin's local data <br />
&nbsp;&nbsp;&nbsp;size_t res = data<tt>-&gt;</tt>frecv(soap, buf, len); // get data from old recv callback <br />
&nbsp;&nbsp;&nbsp;fwrite(buf, res, 1, stderr); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;res; <br />
}
</td></tr></table><br></i>
The <i>fdelete</i> callback of <i><b>struct</b>&nbsp;soap_plugin</i>
MUST be set to register the plugin. It is the responsibility of the plug-in to
handle registry (init), copy, and deletion of the plug-in data and callbacks.

<div class="p"><!----></div>
A plugin is copied with the <i>soap_copy()</i> call. This function copies a soap struct
and the chain of plugins. It is up to the plugin implementation to share the plugin data
or not: 

<ol type="1">
<li> if the <i>fcopy()</i> callback is set by the plugin initialization, this callback will be called to allow
the plugin to copy its local data upon a <i>soap_copy()</i> call. When <i>soap_done()</i> is called on
the soap struct copy, the <i>fdelete()</i> callback is called for deallocation and cleanup of the local data.
<div class="p"><!----></div>
</li>

<li>
if the <i>fcopy()</i> callback is not set, then the plugin data
will be shared (i.e. the data pointer points to the same address).
The <i>fdelete()</i> callback will not be called upon a <i>soap_done()</i> on a
copy of the soap struct. The <i>fdelete()</i> callback will be called for
the original soap struct with which the plugin was registered.
<div class="p"><!----></div>
</li>
</ol>
The example plug-in should be used as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;soap soap; <br />
soap_init(&amp;soap); <br />
soap_register_plugin(&amp;soap, plugin); <br />
... <br />
soap_done(&amp;soap);
</td></tr></table><br></i>
Note: <i>soap_register_plugin(...)</i> is an alias for
<i>soap_register_plugin_arg(..., NULL)</i>. That is, it passes NULL as an
argument to plug-in's registry callback.

<div class="p"><!----></div>
A number of example plug-ins are included in the gSOAP package's <i>plugin</i> directory. Some of these plug-ins are discussed.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.38.1">
19.38.1</a>&nbsp;&nbsp;<font color="#0000FF">The Message Logging and Statistics Plug-in</font></h4>

<div class="p"><!----></div>
The message logging and access statistics plug-in can be used to selectively log inbound and outbound messages to a file or stream. It also keeps access statistics to log the total number of bytes sent and received.

<div class="p"><!----></div>
To use the plug-in, compile and link your application with <i>logging.c</i> located in the <i>plugin</i> directory of the package.
To enable the plug-in in your code, register the plug-in and set the streams as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "logging.h" <br />
size_t bytes_in; <br />
size_t bytes_out; <br />
... <br />
<b>if</b>&nbsp;(soap_register_plugin(&amp;soap, logging)) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // failed to register <br />
... <br />
soap_set_logging_inbound(&amp;soap, stdout); <br />
soap_set_logging_outbound(&amp;soap, stdout); <br />
... process messages ... <br />
soap_set_logging_inbound(&amp;soap, NULL); // disable logging <br />
soap_set_logging_outbound(&amp;soap, NULL); // disable logging <br />
soap_get_logging_stats(&amp;soap, &amp;bytes_out, &amp;bytes_in);
</td></tr></table><br></i>
If you use <i>soap_copy</i> to copy the soap struct with the plug-in, the plug-in's data will be shared by the copy.
Therefore, the statistics are not 100% guaranteed to be accurate for multi-threaded services since race conditions on the counters may occur. Mutex is not used to update the counters to avoid introducing expensive synchronization points. If 100% server-side accuracy is required, add mutex at the points indicated in the <i>logging.c</i> code.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.38.2">
19.38.2</a>&nbsp;&nbsp;<font color="#0000FF">RESTful Interface: The HTTP GET Plug-in</font></h4>

<div class="p"><!----></div>
Client-side and server-side use of RESTful HTTP GET operations are supported with the HTTP GET plug-in <i>plugin/httpget.c</i>.
The HTTP GET plug-in allows your server to handle RESTful HTTP GET requests and
at the same time still serve SOAP-based POST requests. The plug-in provides support to client applications to issue HTTP GET operations to a server.

<div class="p"><!----></div>
Note that HTTP GET requests can also be handled at the server side with the
<i>fget</i> callback, see Section&nbsp;<a href="#sec:callback">19.7</a>. However, the HTTP GET
plug-in also keeps statistics on the number of successful POST and GET
exchanges and failed operations (HTTP faults, SOAP Faults, etc.). It also keeps
hit histograms accumulated for up to a year of runtime.

<div class="p"><!----></div>
To use the plug-in, compile and link your application with <i>httpget.c</i> located in the <i>plugin</i> directory of the package.
To enable the plug-in in your code, register the plug-in with your HTTP GET handler function as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "httpget.h" <br />
... <br />
<b>if</b>&nbsp;(soap_register_plugin_arg(&amp;soap, httpget, (<b>void</b>*)my_http_get_handler)) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // failed to register <br />
... <br />
<b>struct</b>&nbsp;http_get_data *httpgetdata; <br />
httpgetdata = (<b>struct</b>&nbsp;http_get_data*)soap_lookup_plugin(&amp;soap, http_get_id); <br />
<b>if</b>&nbsp;(!httpgetdata) <br />
&nbsp;&nbsp;&nbsp;... // if the plug-in registered OK, there is certainly data but can't hurt to check <br />
... process messages ... <br />
size_t get_ok = httpgetdata<tt>-&gt;</tt>stat_get; <br />
size_t post_ok = httpgetdata<tt>-&gt;</tt>stat_post; <br />
size_t errors = httpgetdata<tt>-&gt;</tt>stat_fail; <br />
... <br />
time_t now = time(NULL); <br />
<b>struct</b>&nbsp;tm *T; <br />
T = localtime(&amp;now); <br />
size_t hitsthisminute = httpgetdata<tt>-&gt;</tt>min[T<tt>-&gt;</tt>tm_min]; <br />
size_t hitsthishour = httpgetdata<tt>-&gt;</tt>hour[T<tt>-&gt;</tt>tm_hour]; <br />
size_t hitstoday = httpgetdata<tt>-&gt;</tt>day[T<tt>-&gt;</tt>tm_yday];
</td></tr></table><br></i>
An HTTP GET handler can simply produce some HTML content, or any other type of content by sending data:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;my_http_get_handler(<b>struct</b>&nbsp;*soap) <br />
{ <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>http_content = "text/html"; <br />
&nbsp;&nbsp;&nbsp;soap_response(soap, SOAP_FILE); <br />
&nbsp;&nbsp;&nbsp;soap_send(soap, &#171;html&#62;Hello&lt;/html&#62;"); <br />
&nbsp;&nbsp;&nbsp;soap_end_send(soap); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; // return SOAP_OK or HTTP error code, e.g. 404 <br />
}
</td></tr></table><br></i>
If you use <i>soap_copy</i> to copy the soap struct with the plug-in, the plug-in's data will be shared by the copy.
Therefore, the statistics are not 100% guaranteed to be accurate for multi-threaded services since race conditions on the counters may occur. Mutex is not used to update the counters to avoid introducing expensive synchronization points. If 100% server-side accuracy is required, add mutex at the points indicated in the <i>httpget.c</i> code.

<div class="p"><!----></div>
The client-side use of HTTP GET is provided by the <i>soap_get_connect</i> operation. To receive a SOAP/XML (response) message <tt>ns:methodResponse</tt>, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "httpget.h" <br />
... <br />
soap_register_plugin(&amp;soap, http_get); <br />
... <br />
<b>if</b>&nbsp;(soap_get_connect(&amp;soap, endpoint, action)) <br />
&nbsp;&nbsp;&nbsp;... connect error ... <br />
<b>else</b>&nbsp;<b>if</b>&nbsp;(soap_recv_ns__methodResponse(&amp;soap, ... params ...)) <br />
&nbsp;&nbsp;&nbsp;... error ... <br />
<b>else</b><br />
&nbsp;&nbsp;&nbsp;... ok ... <br />
soap_destroy(&amp;soap); <br />
soap_end(&amp;soap); <br />
soap_done(&amp;soap);
</td></tr></table><br></i>
To receive any HTTP Body data into a buffer, use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "httpget.h" <br />
... <br />
<b>char</b>&nbsp;*response = NULL; <br />
soap_register_plugin(&amp;soap, http_get); <br />
... <br />
<b>if</b>&nbsp;(soap_get_connect(&amp;soap, endpoint, NULL)) <br />
&nbsp;&nbsp;&nbsp;... connect error ... <br />
<b>else</b>&nbsp;<b>if</b>&nbsp;(soap_begin_recv(&amp;soap)) <br />
&nbsp;&nbsp;&nbsp;... error ... <br />
<b>else</b><br />
&nbsp;&nbsp;&nbsp;response = soap_get_http_body(&amp;soap); <br />
soap_end_recv(&amp;soap); <br />
... use the 'response' string (NULL indicates no body or error) <br />
soap_destroy(&amp;soap); <br />
soap_end(&amp;soap); <br />
soap_done(&amp;soap);
</td></tr></table><br></i>

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.38.3">
19.38.3</a>&nbsp;&nbsp;<font color="#0000FF">RESTful Interface: The HTTP POST Plug-in</font></h4>

<div class="p"><!----></div>
Client-side and server-side use of RESTful HTTP POST, PUT, and DELETE
operations are supported with the HTTP POST plug-in <i>plugin/httppost.c</i>.

<div class="p"><!----></div>
The HTTP POST plug-in allows your server to handle RESTful HTTP POST requests
and at the same time still serve SOAP-based POST requests. The plug-in also
provides support for client applications to issue HTTP POST operations to a
server.

<div class="p"><!----></div>
To simplify the server-side handling of POST requests, handlers can be associated with media types:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>struct</b>&nbsp;http_post_handlers my_handlers[] = <br />
{ { "image/jpg", jpeg_handler }, <br />
&nbsp;&nbsp;&nbsp;{ "image/ *",   image_handler }, <br />
&nbsp;&nbsp;&nbsp;{ "text/html", html_handler }, <br />
&nbsp;&nbsp;&nbsp;{ "text/ *",    text_handler }, <br />
&nbsp;&nbsp;&nbsp;{ "text/ *;*",  text_handler }, <br />
&nbsp;&nbsp;&nbsp;{ "POST",  generic_POST_handler }, <br />
&nbsp;&nbsp;&nbsp;{ "PUT",  generic_PUT_handler }, <br />
&nbsp;&nbsp;&nbsp;{ "DELETE",  generic_DELETE_handler }, <br />
&nbsp;&nbsp;&nbsp;{ NULL } <br />
};
</td></tr></table><br></i>
Note that '*' can be used as a wildcard and some media types may have
optional parameters (after ';'). The handlers are functions that will be
invoked when a POSTed request message matching media type is send to the
server.

<div class="p"><!----></div>
An example image handler that checks the specific image type:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>int</b>&nbsp;image_handler(struct soap *soap) <br />
{ <b>const</b>&nbsp;<b>char</b>&nbsp;*buf; <br />
&nbsp;&nbsp;&nbsp;size_t len; <br />
&nbsp;&nbsp;&nbsp;// if necessary, check type in soap-&#62;http_content <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap-&#62;http_content &amp;&amp; !soap_tag_cmp(soap-&#62;http_content, "image/gif") <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;404; // HTTP error 404 <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_http_body(soap, &amp;buf, &amp;len) != SOAP_OK) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;soap-&#62;error; <br />
&nbsp;&nbsp;&nbsp;// ... now process image in buf <br />
&nbsp;&nbsp;&nbsp;// reply with empty HTTP OK response: <br />
&nbsp;&nbsp;&nbsp;soap_response(soap, SOAP_OK); <br />
&nbsp;&nbsp;&nbsp;soap_end_send(soap); <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
}
</td></tr></table><br></i>
The HTTP POST plug-in provides a <i>soap_http_body</i> operation as illustrated above to copy the HTTP Body content into a buffer.

<div class="p"><!----></div>
The above example returns HTTP OK. If content is supposed to be returned, then use:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
&nbsp;&nbsp;&nbsp;soap-&#62;http_content = "image/jpeg"; // a jpeg image to return back <br />
&nbsp;&nbsp;&nbsp;soap_response(soap, SOAP_FILE); // SOAP_FILE sets custom http content <br />
&nbsp;&nbsp;&nbsp;soap_send_raw(soap, buf, len); // send image <br />
&nbsp;&nbsp;&nbsp;soap_end_send(soap);
</td></tr></table><br></i>

<div class="p"><!----></div>
For client applications to use HTTP POST, use the <i>soap_post_connect</i> operation:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>char</b>&nbsp;*buf; // holds the HTTP request/response body data <br />
size_t len; // length of data <br />
... <br />
<b>if</b>&nbsp;(soap_post_connect(soap, "URL", "SOAP action or NULL", "media type") <br />
&nbsp;&nbsp;&nbsp;<tt>||</tt> soap_send_raw(soap, buf, len); <br />
&nbsp;&nbsp;&nbsp;<tt>||</tt> soap_end_send(soap)) <br />
&nbsp;&nbsp;&nbsp;... error ... <br />
<b>if</b>&nbsp;(soap_begin_recv(&amp;soap) <br />
&nbsp;&nbsp;&nbsp;<tt>||</tt> soap_http_body(&amp;soap, &amp;buf, &amp;len) <br />
&nbsp;&nbsp;&nbsp;<tt>||</tt> soap_end_recv(&amp;soap)) <br />
&nbsp;&nbsp;&nbsp;... error ... <br />
// ... use buf[0..len-1] <br />
soap_end(soap);
</td></tr></table><br></i>
Similarly, <i>soap_put_connect</i> and <i>soap_delete_connect</i> commands are provided for PUT and DELETE handling.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.38.4">
19.38.4</a>&nbsp;&nbsp;<font color="#0000FF">The HTTP MD5 Checksum Plug-in</font></h4>

<div class="p"><!----></div>
The HTTP MD5 plug-in works in the background to automatically verify the
content of messages using MD5 checksums. With the plug-in, messages can be
transferred over (trusted but) unreliable connections. The plug-in can be used
on the client side and server side.

<div class="p"><!----></div>
To use the plug-in, compile and link your application with <i>httpmd5.c</i> and <i>md5evp.c</i> located in the <i>plugin</i> directory of the package. The <i>md5evp.c</i> implementation uses the EVP interface to compute MD5 checksums with OpenSSL (compiled with <i>-DWITH_OPENSSL</i>).

<div class="p"><!----></div>
To enable the plug-in in your code, register the plug-in as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "httpmd5.h" <br />
... <br />
<b>if</b>&nbsp;(soap_register_plugin(&amp;soap, http_md5)) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // failed to register
</td></tr></table><br></i>
Once registered, MD5 checksums are produced for all outbound messages. Inbound messages with MD5 checksums in the HTTP header are automatically verified.

<div class="p"><!----></div>
The plug-in requires you to set the <i>SOAP_IO_STORE</i> flag when sending SOAP with attachments:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "httpmd5.h" <br />
... <br />
<b>struct</b>&nbsp;soap soap; <br />
soap_init1(&amp;soap, SOAP_IO_STORE); <br />
<b>if</b>&nbsp;(soap_register_plugin(&amp;soap, http_md5) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // failed to register <br />
... now safe to send SOAP with attachments ...
</td></tr></table><br></i>
Unfortunately, this eliminates streaming.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.38.5">
19.38.5</a>&nbsp;&nbsp;<font color="#0000FF">The HTTP Digest Authentication Plug-in</font></h4>

<div class="p"><!----></div>
The HTTP digest authentication plug-in enables a more secure authentication
scheme compared to basic authentication. HTTP basic authentication sends
unencrypted userids and passwords over the net, while digest authentication
does not exchange passwords but exchanges checksums of passwords (and other
data such as nonces to avoid replay attacks). For more details, please see
RFC 2617.

<div class="p"><!----></div>
The HTTP digest authentication can be used next to the built-in basic
authentication, or basic authentication can be rejected to tighten security.
The server must have a database with userid's and passwords (in plain text
form). The client, when challenged by the server, checks the authentication
realm provided by the server and sets the userid and passwords for digest
authentication. The client application can temporarily store the userid and
password for a sequence of message exchanges with the server, which is faster
than repeated authorization challenges and authentication responses.

<div class="p"><!----></div>
At the client side, the plug-in is registered and service invocations are
checked for authorization challenges (HTTP error code 401). When the server
challenges the client, the client should set the userid and password and retry
the invocation. The client can determine the userid and password based on the
authentication realm part of the server's challenge. The authentication information can be temporarily saved for multiple invocations.

<div class="p"><!----></div>
Client-side example:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "httpda.h" <br />
... <br />
<b>if</b>&nbsp;soap_register_plugin(&amp;soap, http_da)) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // failed to register <br />
... <br />
<b>if</b>&nbsp;(soap_call_ns__method(&amp;soap, ...) != SOAP_OK) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap.error == 401) // challenge: HTTP authentication required <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!strcmp(soap.authrealm, authrealm)) // determine authentication realm
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>struct</b>&nbsp;http_da_info info; // to store userid and passwd <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;http_da_save(&amp;soap, &amp;info, authrealm, userid, passwd); // set userid and passwd for this realm<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap_call_ns__method(&amp;soap, ...) == SOAP_OK) // retry <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ ... <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;soap_end(&amp;soap); // userid and passwd were deallocated <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;http_da_restore(&amp;soap, &amp;info); // restore userid and passwd <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!soap_call_ns__method(&amp;soap, ...) == SOAP_OK) // another call <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;http_da_release(&amp;soap, &amp;info); // remove userid and passwd
</td></tr></table><br></i>
This code supports both basic and digest authentication.

<div class="p"><!----></div>
The server can challenge a client using HTTP code 401. With the plug-in, HTTP digest authentication challenges are send. Without the plug-in, basic authentication challenges are send.

<div class="p"><!----></div>
Each server method can implement authentication as desired and may enforce
digest authentication or may also accept basic authentication responses. To
verify digest authentication responses, the server should compute and compare
the checksums using the plug-in's <i>http_da_verify_post</i> function for
HTTP POST requests (and <i>http_da_verify_get</i> for HTTP GET requests with
the HTTP GET plugin) as follows:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#include "httpda.h" <br />
... <br />
<b>if</b>&nbsp;(soap_register_plugin(&amp;soap, http_da)) <br />
&nbsp;&nbsp;&nbsp;soap_print_fault(&amp;soap, stderr); // failed to register <br />
... <br />
soap_serve(&amp;soap); <br />
... <br />
<b>int</b>&nbsp;ns__method(<b>struct</b>&nbsp;soap *soap, ...) <br />
{ <br />
&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(soap<tt>-&gt;</tt>userid &amp;&amp; soap<tt>-&gt;</tt>passwd) // client used basic authentication <br />
&nbsp;&nbsp;&nbsp;{ // may decide not to handle, but if ok then go ahead and compare info: <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!strcmp(soap<tt>-&gt;</tt>userid, userid) &amp;&amp; !strcmp(soap<tt>-&gt;</tt>passwd, passwd)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ ... handle request ... <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;<b>else</b>&nbsp;<b>if</b>&nbsp;(soap<tt>-&gt;</tt>authrealm &amp;&amp; soap<tt>-&gt;</tt>userid) // Digest authentication <br />
&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;passwd = ... // database lookup on userid and authrealm to find passwd <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!strcmp(soap<tt>-&gt;</tt>authrealm, authrealm) &amp;&amp; !strcmp(soap<tt>-&gt;</tt>userid, userid)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>if</b>&nbsp;(!http_da_verify_post(soap, passwd)) <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ ... handle request ... <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;SOAP_OK; <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;} <br />
&nbsp;&nbsp;&nbsp;soap<tt>-&gt;</tt>authrealm = authrealm; // set realm for challenge <br />
&nbsp;&nbsp;&nbsp;<b>return</b>&nbsp;401; // Not authorized, challenge digest authentication <br />
}
</td></tr></table><br></i>

<div class="p"><!----></div>
For more details, including how to configure HTTP Digest authentication for
proxies, please see the <i>doc/httpda/html/index.html</i> documentation in the gSOAP package.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.38.6">
19.38.6</a>&nbsp;&nbsp;<font color="#0000FF">The WS-Addressing Plug-in</font></h4>

<div class="p"><!----></div>
The WSA WS-Addressing plug-in and the source code are extensively documented in
the <i>doc/wsa</i> directory of the gSOAP package. Please refer to the documentation
included in the package.

<div class="p"><!----></div>
The plug-in code is located in the <i>plugin</i> directory:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><i>wsaapi.h</i> and <i>wsaapi.c</i> </td><td align="left">WS-Addressing plugin (C and C++) </td></tr></table>

</td></tr></table><br></span>
To enable WS-Addressing 2005 (and support for 8/2004), the service definitions header file for <i>soapcpp2</i> should include the following imports:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "import/wsa5.h"
</td></tr></table><br></i>
This imports the SOAP header elements required by WS-Addressing.

<div class="p"><!----></div>
For more details, please see the <i>doc/wsa/html/index.html</i> documentation in the gSOAP package.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.38.7">
19.38.7</a>&nbsp;&nbsp;<font color="#0000FF">The WS-ReliableMessaging Plug-in</font></h4>

<div class="p"><!----></div>
The WSRM WS-ReliableMessaging plug-in and the source code are extensively documented in
the <i>doc/wsrm</i> directory of the gSOAP package. Please refer to the documentation
included in the package.

<div class="p"><!----></div>
The plug-in code is located in the <i>plugin</i> directory:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><i>wsrmapi.h</i> and <i>wsrmapi.c</i> </td><td align="left">WS-ReliableMessaging plugin (C and C++) </td></tr></table>

</td></tr></table><br></span>
Also needed are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><i>threads.h</i> and <i>threads.c</i> </td><td align="left">Multithreading and locking support </td></tr></table>

</td></tr></table><br></span>
To enable WS-ReliableMessaging, the service definitions header file for <i>soapcpp2</i> should include the following imports:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "import/wsrm.h" <br />
#import "import/wsa5.h"
</td></tr></table><br></i>
This imports the SOAP header elements required by WS-ReliableMessaging.

<div class="p"><!----></div>
For more details, please see the <i>doc/wsrm/html/index.html</i> documentation in the gSOAP package.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.38.8">
19.38.8</a>&nbsp;&nbsp;<font color="#0000FF">The WS-Security Plug-in</font></h4>

<div class="p"><!----></div>
The WSSE WS-Security plug-in and the source code are extensively documented in
the <i>doc/wsse</i> directory of the gSOAP package. Please refer to the
documentation included in the package for details.

<div class="p"><!----></div>
The plug-in code is located in the <i>plugin</i> directory:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><i>wsseapi.h</i> and <i>wsseapi.c</i> </td><td align="left">WS-Security plugin (C and C++) </td></tr></table>

</td></tr></table><br></span>
Also needed are:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#D0D0D0"><tr><td><span class="roman">

<table>
<tr><td align="left"><i>smdevp.h</i> and <i>smdevp.c</i> </td><td align="left">Streaming XML signature and message digest engine </td></tr>
<tr><td align="left"><i>mecevp.h</i> and <i>mecevp.c</i> </td><td align="left">Streaming XML encryption engine </td></tr>
<tr><td align="left"><i>threads.h</i> and <i>threads.c</i> </td><td align="left">Multithreading and locking support </td></tr></table>

</td></tr></table><br></span>
To enable WS-Secrutiy, the service definitions header file for <i>soapcpp2</i> should include the following imports:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
#import "import/wsse.h"
</td></tr></table><br></i>
This imports the SOAP header elements required by WS-Security.

<div class="p"><!----></div>
For more details, please see the <i>doc/wsse/html/index.html</i> documentation in the gSOAP package.

<div class="p"><!----></div>
		      <h4><a name="tth_sEc19.38.9">
19.38.9</a>&nbsp;&nbsp;<font color="#0000FF">WS-Discovery</font></h4>

<div class="p"><!----></div>
The WS-Discovery implementation is documented in the <i>doc/wsdd</i> directory
of the gSOAP package. Please refer to the documentation included in the package
for details.

<div class="p"><!----></div>
Basically, to add WS-Discovery support the following event handlers must be
defined and linked:
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>void</b>&nbsp;wsdd_event_Hello(<b>struct</b>&nbsp;soap *soap, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;InstanceId, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*SequenceId, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;MessageNumber, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*MessageID, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*RelatesTo, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*EndpointReference, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*Types, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*Scopes, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*MatchBy, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*XAddrs, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;MetadataVersion)
</td></tr></table><br></i>

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>void</b>&nbsp;wsdd_event_Bye(<b>struct</b>&nbsp;soap *soap, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;InstanceId, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*SequenceId, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;MessageNumber, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*MessageID, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*RelatesTo, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*EndpointReference, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*Types, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*Scopes, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*MatchBy, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*XAddrs, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;MetadataVersion)
</td></tr></table><br></i>

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_wsdd_mode wsdd_event_Probe(<b>struct</b>&nbsp;soap *soap, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*MessageID, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*ReplyTo, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*Types, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*Scopes, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*MatchBy, <br />
<b>struct</b>&nbsp;wsdd__ProbeMatchesType *ProbeMatches)
</td></tr></table><br></i>

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>void</b>&nbsp;wsdd_event_ProbeMatches(<b>struct</b>&nbsp;soap *soap, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;InstanceId, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*SequenceId, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;MessageNumber, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*MessageID, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*RelatesTo, <br />
<b>struct</b>&nbsp;wsdd__ProbeMatchesType *ProbeMatches)
</td></tr></table><br></i>

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
soap_wsdd_mode wsdd_event_Resolve(<b>struct</b>&nbsp;soap *soap, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*MessageID, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*ReplyTo, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*EndpointReference, <br />
<b>struct</b>&nbsp;wsdd__ResolveMatchesType *ResolveMatches)
</td></tr></table><br></i>

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>void</b>&nbsp;wsdd_event_ResolveMatches(<b>struct</b>&nbsp;soap *soap, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;InstanceId, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*SequenceId, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;MessageNumber, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*MessageID, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*RelatesTo, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*EndpointReference, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*Types, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*Scopes, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*MatchBy, <br />
<b>const</b>&nbsp;<b>char</b>&nbsp;*XAddrs, <br />
<b>unsigned</b>&nbsp;<b>int</b>&nbsp;MetadataVersion)
</td></tr></table><br></i>

<div class="p"><!----></div>
These event handlers will be invoked when inbound WS-Discovery messages arrive using:

<div class="p"><!----></div>
<br><br><table border=0 width="100%" cellpadding="8" bgcolor="#B0D0B0"><tr><td><i>
<b>if</b>&nbsp;(!soap_valid_socket(soap_bind(soap, NULL, port, 100))) <br />
&nbsp;&nbsp;&nbsp;.. error <br />
<b>if</b>&nbsp;(soap_wsdd_listen(soap, timeout)) <br />
&nbsp;&nbsp;&nbsp;... error
</td></tr></table><br></i>
which will listen for <i>timeout</i> seconds to inbound WS-Discovery messages
on a port and dispatches them to the event handlers. A negative <i>timeout</i> is measured
in ns.

<div class="p"><!----></div>
</body>

<br /><br /><hr /><small>File translated from
T<sub><font size="-1">E</font></sub>X
by <a href="http://hutchinson.belmont.ma.us/tth/">
T<sub><font size="-1">T</font></sub>Hgold</a>,
version 4.00.<br />On 12 Apr 2015, 15:39.</small>
</html>
